Online HTTP interface
The online service speaks JSON over HTTP. On this site it is reached as /api/... (the site forwards /api/* to the service's /v1/*). Sign in with the session cookie or send Authorization: Bearer <token> (a personal token from your settings, or a game token). Errors come as { "error": "<code>", "message": "<text>" } with the usual HTTP status. Routes marked admin need an administrator; routes under /v1/servers are for game servers and need their host key.
This page is generated from server/online/openapi.yaml; a test fails when the service gets a route that the file does not list, so the list below is complete. Request and response fields are described in the online service page.
Service
| Method | Path | What it does |
|---|---|---|
| GET | /v1/health |
Version and build, no auth |
| GET | /v1/healthz |
Liveness, plain "ok" |
| GET | /v1/stats/history |
Totals once a minute for the last 24 hours (games, players, queue, requests), for the status page |
| GET | /v1/readyz |
Readiness (the database answers) |
| GET | /v1/metrics |
Prometheus metrics, admin only |
| GET | /v1/kinds |
Item kinds that can be uploaded |
Accounts and sign-in
| Method | Path | What it does |
|---|---|---|
| POST | /v1/signup |
Create an account, sends a verification mail |
| POST | /v1/login |
Sign in, sets the session cookie |
| POST | /v1/logout |
End this session |
| POST | /v1/login/passkey/begin |
Start a passkey sign-in (only when the service enables passkeys) |
| POST | /v1/login/passkey/finish |
Finish a passkey sign-in with the device's signed answer |
| GET | /v1/me/passkeys |
Your registered passkeys |
| POST | /v1/me/passkeys/begin |
Start registering a passkey |
| POST | /v1/me/passkeys/finish |
Finish registering a passkey |
| DELETE | /v1/me/passkeys/{id} |
Remove a passkey |
| POST | /v1/verify |
Confirm an email address with the mailed code |
| POST | /v1/verify/resend |
Send the verification mail again |
| POST | /v1/password/forgot |
Mail a password-reset code |
| POST | /v1/password/reset |
Set a new password with the code |
Your account
| Method | Path | What it does |
|---|---|---|
| GET | /v1/me |
The signed-in account (name, muted, muted_until, rating...) |
| PATCH | /v1/me |
Rename the account |
| DELETE | /v1/me |
Delete the account |
| POST | /v1/me/game-token |
Make a short-lived token for joining a dedicated server |
| DELETE | /v1/me/game-token |
Revoke all game tokens |
| GET | /v1/me/tokens |
List personal tokens |
| POST | /v1/me/tokens |
Create a personal token with scopes |
| DELETE | /v1/me/tokens/{id} |
Revoke one personal token |
| GET | /v1/me/sessions |
List signed-in sessions |
| DELETE | /v1/me/sessions |
Sign out every other session |
| DELETE | /v1/me/sessions/{id} |
Sign out one session |
| POST | /v1/me/password |
Change the password |
| POST | /v1/me/email |
Change the email address (needs verification) |
| GET | /v1/me/stats |
My wins, losses and rating per mode |
| GET | /v1/me/profile |
My profile (avatar, bio, privacy settings) |
| PATCH | /v1/me/profile |
Change my profile settings |
| GET | /v1/me/export |
Export all my data as JSON |
| POST | /v1/me/totp/setup |
Start two-step sign-in setup (secret and provisioning URI) |
| POST | /v1/me/totp/enable |
Turn on two-step sign-in with a first code |
| POST | /v1/me/totp/disable |
Turn off two-step sign-in (needs a code) |
| GET | /v1/me/active-game |
The running game I am seated in, for Rejoin |
| GET | /v1/mentions |
Chat lines that mention me |
| POST | /v1/me/claim-guest |
Move the history rows of guest games (proved by the sha256 of the guest secret) to my account, once |
Games, servers and ratings
| Method | Path | What it does |
|---|---|---|
| GET | /v1/games |
The open and running games list |
| POST | /v1/games |
Host a game (lobby entry) |
| POST | /v1/games/{id}/heartbeat |
Keep a hosted game listed |
| POST | /v1/games/{id}/join |
Join a listed game |
| POST | /v1/games/{id}/leave |
Leave a listed game |
| POST | /v1/servers/games |
A dedicated server lists its game (host key) |
| POST | /v1/servers/games/{id}/heartbeat |
A dedicated server's heartbeat with seated accounts |
| DELETE | /v1/servers/games/{id} |
A dedicated server ends its listing |
| POST | /v1/servers/history |
A dedicated server reports a finished game |
| POST | /v1/servers/reports |
A dedicated server files an in-game player report with a pointer to its evidence (host key) |
| PUT | /v1/servers/history/{id}/replay |
Upload the replay of a finished game |
| POST | /v1/servers/history/{id}/chat |
Upload the chat of a finished game |
| GET | /v1/history |
Finished games, newest first |
| GET | /v1/history/{id} |
One finished game with results |
| GET | /v1/history/{id}/replay |
Download the replay |
| GET | /v1/history/{id}/chat |
The chat of that game |
| GET | /v1/queue |
My matchmaking queue status |
| POST | /v1/queue |
Join the matchmaking queue |
| DELETE | /v1/queue |
Leave the queue |
| POST | /v1/queue/claim |
Claim the match that was found |
| GET | /v1/leaderboard |
Ranking per mode with rating deviation |
Chat and social
| Method | Path | What it does |
|---|---|---|
| GET | /v1/chat |
Read the lobby chat (after=, wait= for long polling) |
| POST | /v1/chat |
Post a chat line |
| GET | /v1/chat/log |
Older chat (moderators and history views) |
| DELETE | /v1/chat/{seq} |
Delete a chat line (moderator) |
| GET | /v1/chat/search |
Search the chat log |
| GET | /v1/announcements |
Current server announcements |
| GET | /v1/chat/stream |
Chat as a server-sent event stream |
| POST | /v1/reports |
Report a player, chat line or item |
| GET | /v1/whispers |
My private messages |
| POST | /v1/whispers |
Send a private message |
| POST | /v1/invites |
Invite a friend to my game |
| GET | /v1/blocks |
Players I blocked |
| POST | /v1/blocks |
Block a player |
| DELETE | /v1/blocks/{id} |
Unblock a player |
| GET | /v1/friends |
My friends and requests |
| POST | /v1/friends |
Send a friend request |
| DELETE | /v1/friends/{id} |
Remove a friend or decline a request |
| POST | /v1/friends/{id}/accept |
Accept a friend request |
| GET | /v1/emotes |
The list of chat emotes |
Shared maps and files
| Method | Path | What it does |
|---|---|---|
| GET | /v1/players/{who} |
A player's public page (name#tag), history hidden when they chose so |
| GET | /v1/avatars |
The built-in avatar choices |
| GET | /v1/items |
Browse uploaded maps, models and mods |
| POST | /v1/items |
Upload an item (multipart) |
| GET | /v1/items/{id} |
One item |
| DELETE | /v1/items/{id} |
Delete my item |
| GET | /v1/items/{id}/download |
Download the item file |
| GET | /v1/items/{id}/thumb |
Thumbnail image (placeholder SVG when none) |
| POST | /v1/items/{id}/like |
Like an item |
| DELETE | /v1/items/{id}/like |
Remove my like |
| GET | /v1/items/{id}/likes |
Like count and whether I liked |
| GET | /v1/items/{id}/versions |
Earlier versions of an item |
| GET | /v1/files/{sha} |
Download a stored file by its hash |
| GET | /v1/capacity |
How many servers and rooms take matches and how many are free, public |
| GET | /v1/items/{id}/info |
Map metadata of an uploaded item (name, size, players) |
| GET | /v1/ranked-maps |
Maps a ranked game may be played on (empty means any) |
| POST | /v1/ranked-maps |
Add a map to the ranked list, moderator |
| DELETE | /v1/ranked-maps/{map} |
Remove a map from the ranked list, moderator |
| GET | /v1/tournaments |
Tournaments, newest first (state open, running or done) |
| POST | /v1/tournaments |
Make a single-elimination 1v1 tournament (2 to 64 entrants) |
| GET | /v1/tournaments/{id} |
One tournament with its entrants and bracket |
| DELETE | /v1/tournaments/{id} |
Cancel an open tournament, owner |
| POST | /v1/tournaments/{id}/enter |
Enter an open tournament |
| DELETE | /v1/tournaments/{id}/enter |
Leave an open tournament |
| POST | /v1/tournaments/{id}/checkin |
Say I am here for my pending match (the 24 hour forfeit favours who checked in) |
| POST | /v1/tournaments/{id}/start |
Seed the entrants by rating and make the bracket, owner |
| POST | /v1/tournaments/{id}/result |
Name the winner of a match without a game (no-show), owner |
| GET | /v1/party |
My party and the parties that invited me |
| POST | /v1/party |
Make a party; I lead it |
| DELETE | /v1/party |
Leave my party (the leader leaving ends it) |
| POST | /v1/party/invite |
The leader invites Name#Tag to the party |
| POST | /v1/party/join |
Join a party I was invited to |
Administrators
| Method | Path | What it does |
|---|---|---|
| GET | /v1/admin/accounts |
Search accounts, admin |
| POST | /v1/admin/accounts/{id}/role |
Set an account's role (user, moderator, admin), admin |
| POST | /v1/admin/announce |
Publish an announcement, admin |
| GET | /v1/admin/slowmode |
Read the chat slow-mode setting, admin |
| POST | /v1/admin/slowmode |
Set the chat slow-mode setting, admin |
| GET | /v1/admin/reports |
Open reports, admin |
| POST | /v1/admin/reports/{id} |
Act on a report (mute, ban, dismiss), admin |
| POST | /v1/feedback |
Send feedback (bug, idea, praise, question) with optional contact, context and screenshot; answers a reference and a one-time delete token |
| DELETE | /v1/feedback/{reference} |
Withdraw your feedback with the delete token |
| GET | /v1/admin/feedback |
The feedback inbox with filters, or ?format=csv, admin |
| GET | /v1/admin/feedback/{id} |
One entry with its context and replay link, admin |
| PATCH | /v1/admin/feedback/{id} |
Set status, note and tags, admin |
| GET | /v1/admin/feedback/{id}/screenshot |
The screenshot picture, admin |
| GET | /v1/admin/log |
The moderation log, admin |
| POST | /v1/admin/games/{id}/void |
Take back the rating changes of a game, moderator |