VRChat API Library for .NET

A .NET client to interact with the unofficial VRChat API. Supports all REST calls specified in https://github.com/vrchatapi/specification.

Disclaimer

This is the official response of the VRChat Team (from Tupper more specifically) on the usage of the VRChat API.

Use of the API using applications other than the approved methods (website, VRChat application) are not officially supported. You may use the API for your own application, but keep these guidelines in mind:

• We do not provide documentation or support for the API.
• Do not make queries to the API more than once per 60 seconds.
• Abuse of the API may result in account termination.
• Access to API endpoints may break at any given time, with no warning.

As stated, this documentation was not created with the help of the official VRChat team. Therefore this documentation is not an official documentation of the VRChat API and may not be always up to date with the latest versions. If you find that a page or endpoint is not longer valid please create an issue and tell us so we can fix it.

Installation

Install with NuGet:

# With .NET CLI
dotnet add package VRChat.API

# Or with Package Manager
Install-Package VRChat.API

If you're working with Depedency Injection like ASP.NET Core or Discord.Net, make sure to also install the DI package

# With .NET CLI
dotnet add package VRChat.API.Extensions.Hosting

# Or with Package Manager
Install-Package VRChat.API.Extensions.Hosting

Getting Started

The following example code authenticates you with the API, fetches your join-date, and prints the name of a world.

If you use manual or email-based two-factor authentication, scroll to the Manual Authentication section below for an example.

using System;
using VRChat.API.Client;

// WithApplication or WithUserAgent is required or VRChat will reject your requests
IVRChat vrchat = new VRChatClientBuilder() // More options available
    .WithUsername("username")
    .WithPassword("password")
    .WithTwoFactorSecret("twoFactorSecret") 
    .WithApplication(name: "Example", version: "1.0.0", contact: "CONTACT_EMAIL")
    .Build();

// Reccomended to set up 2FA on your account for seamless login

// There is also IVRChat.TryLoginAsync()
var currentUser = await vrchat.LoginAsync();
Console.WriteLine($"Logged in as {currentUser.DisplayName}!");

var user = await vrchat.Users.GetUserAsync("usr_f2049d71-e76b-42d2-a8bd-43deec9c004e");
Console.WriteLine($"Found user {user.DisplayName}, joined at {user.DateJoined}");

var world = await vrchat.Worlds.GetWorldAsync("wrld_ba913a96-fac4-4048-a062-9aa5db092812");
Console.WriteLine($"Found world {world.Name}, with {world.Visits} visits");

The builder is quite flexible and will let you customize as you see fit.

Cookies

You can fetch the cookies that the API client has using the IVRChat.GetCookies() method.

var cookies = vrchat.GetCookies(); // List<Cookie>

You can set the cookies yourself by attaching them during the client building process.

IVRChat vrchat = new VRChatClientBuilder()
    .WithUsername("username")
    .WithPassword("password")
    .WithTwoFactorSecret("twoFactorSecret") 
    .WithApplication(name: "Example", version: "1.0.0", contact: "CONTACT_EMAIL")
    .WithAuthCookie("auth cookie", "twoFactorAuth cookie")
    .Build();

Depedency Injection

Working with Microsoft DI is easy, after installing the DI package VRChat.API.Extensions.Hosting, you can easily attach it to your .NET DI Host, including ASP.NET Core, .NET Aspire, and Discord.Net

// assuming you have a IServiceCollection services defined somewhere

// Fluent builder
services.AddVRChat(builder => builder.WithUsername("username"));

// Named clients
services.AddVRChat("WorldsClient", builder => builder.WithUsername("username"))

// Loading from IConfiguration (supports env, file, and user-secrets)
services.AddVRChat(builder.Configuration.GetSection("VRChat"))

To see the available options for loading from an IConfiguration see VRChatOptions.cs

Working with named clients

Instead of requesting an IVRChat from services, you will request an IVRChatClientFactory. Unnamed clients will have a default name of vrc_default and registering multiple will overwrite the previous one.

public class MyController : Controller
{
    [HttpGet("/worlds/active")]
    public async Task<IActionResult> GetActiveWorldsAsync([FromServices] IVRChatClientFactory factory)
    {
        var vrchat = factory.CreateClient("WorldsClient");

        var worlds = await vrchat.Worlds.GetActiveWorldsAsync();

        return Ok(worlds);
    }
}

Example Projects

Console app (login): see VRChat.API.Examples.Console

ASP.NET Core (depedency injection): see VRChat.API.Examples.AspNetCore

Manually authenticating

Sometimes, we don't have two-factor authentication set up on our accounts. While it's reccomended for most bots or apps, your app may be a WPF/WinForms application that requires user credential input. In these cases, the LoginAsync() methods on IVRChat won't work, because they only support token-based two-factor authentication.

Here is an example of how you can implement this in the .NET SDK:

using System;
using VRChat.API.Client;
using VRChat.API.Model;

// WithApplication or WithUserAgent is required or VRChat will reject your requests
IVRChat vrchat = new VRChatClientBuilder() // More options available
    .WithUsername("username")
    .WithPassword("password")
    .WithApplication(name: "Example", version: "1.0.0", contact: "CONTACT_EMAIL")
    .Build();

var response = await vrchat.Authentication.GetCurrentUserAsync();

if(response.RequiresTwoFactorAuth.Contains("emailOtp"))
{
    Console.WriteLine("An verification code was sent to your email address!");
    Console.Write("Enter code: ");
    string code = Console.ReadLine();
    var otpResponse = await vrchat.Authentication.Verify2FAEmailCodeAsync(new TwoFactorEmailCode(code));
}
else if(response.RequiresTwoFactorAuth.Contains("totp"))
{
    Console.WriteLine("Please use your authenticator application to get the two-factor code.");
    Console.Write("Enter code: ");
    string code = Console.ReadLine();
    var otpResponse = await vrchat.Authentication.Verify2FAAsync(new TwoFactorAuthCode(code));
}

var user = await vrchat.Authentication.GetCurrentUserAsync();

Console.WriteLine($"Logged in as {user.DisplayName}!");

Working with the raw generated wrapper yourself

The following example code showcases how you can work with the raw generated library yourself.

This is not the reccomended way but can be used for very specific use cases.

using System;
using VRChat.API.Api;
using VRChat.API.Client;
using VRChat.API.Model;

// Create a configuration for us to log in
Configuration config = new Configuration();
config.Username = "Username";
config.Password = "Password";

// We have to identify ourselves according to the vrchat tos,
// We can't use emails here bc http header parser complains
config.UserAgent = "ExampleProgram/0.0.1 mydiscordusername"; 

// Create a client to hold all our cookies :D
ApiClient client = new ApiClient();

// Create an instance of the auth api so we can verify and log in
AuthenticationApi authApi = new AuthenticationApi(client, client, config);

// We also need to create instances of the other APIs we'll need
UsersApi userApi = new UsersApi(client, client, config);
WorldsApi worldApi = new WorldsApi(client, client, config);

try
{
    // Our first request we get the ApiResponse instead of just the user object,
    // so we can see what the API expects from us
    ApiResponse<CurrentUser> currentUserResp = authApi.GetCurrentUserWithHttpInfo();

    if(currentUserResp.Data.RequiresTwoFactorAuth?.Count > 0)
    {
        if (currentUserResp.Data.RequiresTwoFactorAuth.Contains("emailOtp")) // If the API wants us to send an Email OTP code
        {
            authApi.Verify2FAEmailCode(new TwoFactorEmailCode("123456"));
        }
        else if(currentUserResp.Data.RequiresTwoFactorAuth.Contains("totp"))
        {
            // authApi.VerifyRecoveryCode(new TwoFactorAuthCode("12345678")); // To Use a Recovery Code
            authApi.Verify2FA(new TwoFactorAuthCode("123456"));
        }
    }

    // We can now get our CurrentUser :D
    CurrentUser currentUser = authApi.GetCurrentUser();
    Console.WriteLine("Logged in as {0}", currentUser.DisplayName);

    User user = userApi.GetUser("usr_f2049d71-e76b-42d2-a8bd-43deec9c004e");
    Console.WriteLine("Found user {0}, joined {1}", user.DisplayName, user.DateJoined);

    World world = worldApi.GetWorld("wrld_ba913a96-fac4-4048-a062-9aa5db092812");
    Console.WriteLine("Found world {0}, visits: {1}", world.Name, world.Visits);
} 
catch (ApiException ex)
{
    // Catch any exceptions write to console, helps w debugging :D
    Console.WriteLine("Exception when calling API: {0}", ex.Message);
    Console.WriteLine("Status Code: {0}", ex.ErrorCode);
    Console.WriteLine(ex.ToString());
}

Cookies (Generated API)

Cookies can be displayed after logging in using:

ApiClient.CookieContainer.GetAllCookies().ToList().ForEach(x => Console.WriteLine($"{x.Name}={x.Value}"));

And they can be used by editing the config at the start of your program like this:

config.DefaultHeaders.Add("Cookie", "auth=[AUTH_COOKIE_HERE]; twoFactorAuth=[TWO_FACTOR_AUTH_COOKIE_HERE]");

Contributing

Contributions are welcome, but do not add features that should be handled by the OpenAPI specification.

Join the Discord server to get in touch with us.