Modbot Docs
API

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/audit

Every 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.

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:

AddressesWhat they are
Everything under /api/auth/ except GET /api/auth/meYour 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-codeMaking 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:

StatusMeaning
200, 204It worked. 204 has no body.
400Something in the request is wrong. detail says what.
401Not 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.
403Signed in, but without a permission this needs (neededPermissions names it), or the account has not linked its VRChat account.
404That thing does not exist.
409It clashes with something that already exists.
429A limit was reached. Some answers carry a Retry-After header with the number of seconds to wait.
502VRChat, Discord or another service Modbot asked turned the request down. detail is what it said.
503Something 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
versionThe Modbot release, as year, month and a number: 2026.9.0.
apiVersionThe API version this server speaks. A plain number that goes up only when something changes in a way that could break a program.
apiVersionMinimumThe 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/reference is a page you can read and try requests from.
  • https://modbot.example.com/api/openapi/v1.json is 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.

In this section

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page