|
| 1 | +# Quick Start |
| 2 | + |
| 3 | +!> **Super Important!** Usege of the API is **NOT** allowed for malicious purposes. Abuse of the API may result in account termination! Please read the [Disclaimer](/README?id=disclaimer) before getting started! |
| 4 | + |
| 5 | +The VRChat API (application programming interface) can be used to programatically retrive or update information regarding your profile, friends, avatars and worlds. The API consists of two parts, "Photon" which is only used in-game, and the "Web API" which is used by both the game and the website, and which is the focus of this documentation. |
| 6 | + |
| 7 | +The Web API operates over the HTTP protocol and transmits data in JSON format. It is what is called [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete), meaning it is stateless, requiring no information of the current state or the request sent previously, and the type of operation is determined by the HTTP method. Almost all API calls also require you to be be authenticated and to abide by the rate-limit. |
| 8 | + |
| 9 | +## Documentation notes |
| 10 | + |
| 11 | +?> These docs are for Unity SDK version `2018.4.20f1` and build tag `master-build-2021-03-26`. |
| 12 | + |
| 13 | +Sections of the documentation labeled **Outdated** means the article or endpoint is no longer supported or that the documentation is out-of-date. Sections labeled **Soon** are work in progress articles, while sections labeled **Beta** are endpoints found in the beta client, and are not yet released into production. |
| 14 | + |
| 15 | +## API Libraries |
| 16 | + |
| 17 | +There are various pre-written libraries which can be used to interact with the API. Depending on the programming languages these libraries are mantained to varying degree, and while most have basic functionality they can lack more unusual endpoitns or not be updated in terms of recent changes to the API. |
| 18 | + |
| 19 | +1. VRCpy (Python) https://github.com/VRChatAPI/VRChatPython |
| 20 | + |
| 21 | +2. ~~VRChat.Net (C#) https://github.com/VRChatAPI/VRChat.Net~~ (outdated) |
| 22 | + |
| 23 | +3. ~~VRChatJava (Java) https://github.com/VRChatAPI/VRChatJava~~ (outdated) |
| 24 | + |
| 25 | +Out of these the Python library is the one most updated, and therefore the most recommended. For other languages it is possible to use a generic HTTP client, such as [Axios](https://github.com/axios/axios) for NodeJS or the new [HttpClient](https://dzone.com/articles/java-11-standardized-http-client-api) in Java 11. There are also graphical API clients such as [Postman](https://www.postman.com/downloads/) and [Insomnia](https://insomnia.rest/download). |
| 26 | + |
| 27 | +This documentation will show examples using curl, a command-line client allowing you to test various endpoints directly without writing a program. Curl can be [downloadable for Windows](https://curl.se/windows/) and installed with `sudo apt-get install curl` on Linux or `brew install curl` on MacOS. |
| 28 | + |
| 29 | +```bash |
| 30 | +$ curl https://api.vrchat.cloud/api/1/health |
| 31 | +{ |
| 32 | + "ok": true, |
| 33 | + "serverName": "prod-api-blue-power-0by", |
| 34 | + "buildVersionTag": "master-build-2021-04-22-ben-bearcrayon" |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +## Client API Key |
| 39 | + |
| 40 | +Every API requires you to give a special API key. To get it simply call the [Remote Config](/SystemAPI/Config.md) endpoint. The API key can be passed in either a query parameter named `apiKey` or by setting a cookie with the name. |
| 41 | + |
| 42 | +?> The last known key is `JlE5Jldo5Jibnk5O5hTx6XVqsJu4WJ26` |
| 43 | + |
| 44 | +```bash |
| 45 | +$ curl https://vrchat.com/api/1/users |
| 46 | +{"error":{"message":"\"No API Key provided!\"","status_code":401}} |
| 47 | +# FAIL: Missing apiKey, as this is a GET request we will provide it as a URL parameter. |
| 48 | + |
| 49 | +$ curl https://vrchat.com/api/1/users?apiKey=JlE5Jldo5Jibnk5O5hTx6XVqsJu4WJ26 |
| 50 | +{"error":{"message":"\"Missing Credentials\"","status_code":401}} |
| 51 | +# SUCCESS: We will now proced to authenticating. |
| 52 | +``` |
| 53 | + |
| 54 | +## Authorization |
| 55 | + |
| 56 | +!> **Session Limit**: Each authentication with login credentials counts as a separate session, out of which you have a limited amount. Make sure to save and reuse the authcookie whenever you can, and avoid sending the Authorization header unless strictly neccesary. |
| 57 | + |
| 58 | +Most of the APIs require you to be authenticated, and VRChat does authorization using the [`Authorization header`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). The username and password are encoded using base64, and then sent to the API endpoint `/api/1/auth/user`. |
| 59 | + |
| 60 | +After authenticating against the API it is **critical** to save and reuse the returned `auth` cookie. Each authentication with login credentials counts as a separate "session", out of which you have a limited amount. Authorization tokens expire either by not using them for a certain period of time, or by using the [`Logout endpoint`](/UserAPI/Logout.md). |
| 61 | + |
| 62 | +```bash |
| 63 | +# Windows (using Powershell) |
| 64 | +$ [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('username:password')) |
| 65 | +dXNlcm5hbWU6cGFzc3dvcmQ= |
| 66 | + |
| 67 | +# Linux / MacOS |
| 68 | +$ echo -n "username:password" | base64 |
| 69 | +dXNlcm5hbWU6cGFzc3dvcmQ= |
| 70 | + |
| 71 | +# Request an authcookie |
| 72 | +# The 'auth' cookie is saved to "cookiejar.txt", this makes it easier to re-use in future commands. |
| 73 | +# Replace the base64-encoded string "Rm9vcmFjazptYXhmYXgyNTI1ISE" with the one generated in one of the previous commands. |
| 74 | +# Also replace "My User Agent" with a custom and unique agent name to identify yourself! |
| 75 | +$ curl -c cookiejar.txt -A "My User Agent" -H "Authorization: Basic Rm9vcmFjazptYXhmYXgyNTI1ISE=" https://api.vrchat.cloud/api/1/auth/user |
| 76 | +``` |
| 77 | + |
| 78 | +For this we will first encode the username and password as base64. We will then authenticate against the API and save the resulting `apiKey` and `auth` cookies to `cookiejar.txt`. We will be using this file in future commands when interacting with the API. In case the auth token expires, simply delete the file and run the command again. |
0 commit comments