API overview
How a program talks to your Modbot, how it signs in, what errors look like, and where the full list of endpoints is.
Everything the Modbot web app shows comes from Modbot's own HTTP API. A script, a bot or another service of yours can use the same API. This section explains how.
Every Modbot is its own server
There is no central Modbot service and no shared API address. Each group runs its own Modbot, and
you talk to that server, at the address it is hosted on. If your web app opens at
https://modbot.example.com, then the API is at https://modbot.example.com/api/....
Every example in these pages uses https://modbot.example.com. Put your own address in its place.
A web page on a different site can call the API from a visitor's browser only if the operator
allows that site with MODBOT_CORS_ORIGINS (see Calling from a web page).
GET /api/server is open to every site. Otherwise, call the API from a program or
a server of your own.
Signing in
The API accepts two kinds of sign-in.
An API key, for programs
Make a key on Settings → API → Keys (see API keys) and send it in the
Authorization header of every request:
curl -H "Authorization: Bearer mbk_..." https://modbot.example.com/api/auditEvery key starts with mbk_. The key acts as the person who made it, with the permissions chosen
for the key, and never more than that person holds at the moment of the request. Anything done with
a key is recorded as done by that person.
Never put a key in an address (?key=...). Addresses end up in logs. Modbot does not read keys
from the address anyway.
The session cookie, for the web app
When someone signs in to the web app, Modbot sets a cookie called modbot.session. The API accepts
that cookie too, which is how the web app itself works. It is meant for the browser, not for your
programs: use a key instead.
Both kinds of sign-in are refused for an account that is disabled. An account that has not linked its VRChat account yet can do almost nothing, and its keys do not work at all.
What a key cannot do
Some parts of the API belong to a person, not to a program. There, a key does not count as a
sign-in at all, whatever permissions it holds, so anything that needs one answers 401:
| Addresses | What they are |
|---|---|
Everything under /api/auth/ except GET /api/auth/me | Your own account: changing your password, username or contact details, signing out everywhere, linking your VRChat account. GET /api/auth/me is allowed, so a program can ask whose key it holds. |
Everything under /api/onboarding/ | The setup wizard. |
/api/companion-devices/pairing-code | Making a code to pair a companion. |
/api/v1/companion/... (any version number) | The companion's own connection, which uses its own device sign-in. |
Everywhere else, the key's permissions decide, exactly as a person's permissions do in the web app.
Errors
Modbot answers with ordinary HTTP status codes, and every error carries the same small JSON body:
code says what went wrong in a word your program can compare, and detail says it in a sentence.
{
"type": "https://docs.modbot.co/api/errors/#invalid-request",
"title": "Request not valid",
"status": 400,
"detail": "A key needs a name.",
"code": "invalid-request",
"error": "A key needs a name."
}Errors lists every code. In short:
| Status | Meaning |
|---|---|
200, 204 | It worked. 204 has no body. |
400 | Something in the request is wrong. detail says what. |
401 | Not signed in: no key, a wrong, expired or revoked key, a key sent where keys are not allowed, or an account that is disabled. A refused key also gets the header WWW-Authenticate: Bearer. Modbot never says whether a key exists. |
403 | Signed in, but without a permission this needs (neededPermissions names it), or the account has not linked its VRChat account. |
404 | That thing does not exist. |
409 | It clashes with something that already exists. |
429 | A limit was reached. Some answers carry a Retry-After header with the number of seconds to wait. |
502 | VRChat, Discord or another service Modbot asked turned the request down. detail is what it said. |
503 | Something Modbot needs for this is not available right now, such as evidence storage. |
Versions
GET /api/version needs no sign-in. It answers:
{ "version": "2026.9.0", "apiVersion": 1, "apiVersionMinimum": 1 }| Field | |
|---|---|
version | The Modbot release, as year, month and a number: 2026.9.0. |
apiVersion | The API version this server speaks. A plain number that goes up only when something changes in a way that could break a program. |
apiVersionMinimum | The oldest API version this server still supports. |
The current API version is 1, and the oldest supported is 1.
The full list of endpoints
The API reference on this site lists every endpoint, with its parameters, answers and the permission it needs. It is made from the same description the server builds from its own code, so it cannot claim something the server does not do.
Your own Modbot also serves its reference:
https://modbot.example.com/api/referenceis a page you can read and try requests from.https://modbot.example.com/api/openapi/v1.jsonis the OpenAPI document itself, which tools can use to generate a client in your language.
Neither needs a sign-in.
What the reference leaves out
A few groups of endpoints are not meant for other programs, so the reference does not list them:
- the setup wizard (
/api/onboarding/...) - the companion's connection and pairing (
/api/v1/companion/...and/api/companion-devices/...) - the page members use to link their Discord account (
/api/discord-link/...), which is driven by a browser and Discord's sign-in - how often Modbot asks VRChat for data (
/api/settings/sync) - the inside of each sync job for the Health page (
/api/health/sync)
They still exist and the web app uses them, but they can change without warning.