Modbot Docs
API

Conventions

The rules every Modbot API endpoint follows, so one endpoint teaches you the rest.

The Modbot API grew one feature at a time, and some early endpoints use their own words for things. This page is the one way to do each thing. Older names and addresses keep working, and the API reference lists the ones on this page.

Names

JSON fields and query parameters are written likeThis. The same idea has the same name everywhere:

ParameterMeansOlder names that still work
searchFree text to look for.q (search, audit log), text (Modbot's log)
statusWhich ones, by where they stand: open, closed, banned.state (flags, reviews, giveaways, Discord members)
vrchatUserIdA person, by their VRChat id.id, userId, vrchat
discordUserIdA person, by their Discord id.discord

When you send both a name from this page and the endpoint's older one, the older one wins, so an existing script never changes meaning.

A VRChat id is passed on exactly as you send it. Modbot never checks its shape, because older VRChat ids follow no pattern.

Addresses and methods

The thing an endpoint acts on is in the address, and the method says what happens to it:

GET /api/thingsList them.
GET /api/things/{id}One of them.
POST /api/thingsMake one.
PUT /api/things/{id}Change one.
DELETE /api/things/{id}Delete one.
POST /api/things/{id}/verbDo something to one that is not a change or a deletion, such as /kick.

A few older endpoints took the id in the body (PUT /api/group/roles) or deleted with POST .../delete. They still work, and each now has a DELETE or PUT at its own address beside it. The reference marks the old ones deprecated and names the new one.

Numbers

Every number in an answer is a JSON number. The reference describes each as an integer or a number, with its size (int32, int64). Modbot also reads a number you send as text, such as "limit": "50", but always answers with a number.

Ids that Modbot makes up itself are either text (most of them) or row numbers that stay far below 2^53, the largest whole number JavaScript holds exactly. The one number above it is a permission bitfield, where Administrator is bit 62: wherever one appears, the permissions' names come beside it (permissionNames). Read the names.

Errors

Every error has the same shape, with a code to branch on. See Errors.

Who is calling

GET /api/auth/me answers with the account a key or a session belongs to. Called with a key, its apiKey field says which key, and what the key may do right now:

{
  "username": "ada",
  "permissionNames": ["ViewMembers", "ViewAuditLog", "ManageApiKeys"],
  "apiKey": {
    "id": "0199a3c4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Discord bot",
    "start": "mbk_3fA9xQ2b",
    "permissionNames": ["ViewAuditLog"],
    "expiresAt": null
  }
}

apiKey.permissionNames is what every request with the key is checked against: the permissions ticked for the key, never more than the account holds now. The permissionNames beside it are the account's own. With a session, apiKey is null.

Calling from a web page

A web page on another address can call the API from a visitor's browser only if the operator allows that address, with the MODBOT_CORS_ORIGINS environment variable:

MODBOT_CORS_ORIGINS=https://tools.example.org,https://dashboard.example.org

* allows every address. With the variable unset, no other address may call the API, as before. GET /api/server is the exception: any page may always read it.

A page on an allowed address signs in with an API key in the Authorization header. Modbot never lets the browser share an answer given to the modbot.session cookie with another address, so a page elsewhere cannot read what the person signed in to Modbot in the same browser can see. Remember that anything a page holds, its visitors can read: give such a key only the permissions the page needs.

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