Öffentliche API · v0BetaDokumentversion 0.1.0

Scoreboards API-Referenz

Lies deine Bestenlisten aus und schreib Ergebnisse hinein – von allem, was eine HTTP-Anfrage senden kann. Neun Endpunkte, ein Schlüssel, kein SDK nötig.

Basis-URL

https://api.scoreboards.dev/v1

OpenAPI-3.1-Dokument Zugang im Dashboard erhalten Bot- und Website-Doku

Die API ist im Beta-Stadium

Der Zugang wird pro Server freigegeben. Öffne dein Dashboard, wähle beim Server, den du verwaltest, den Bereich API und frage den Zugang dort an; danach kannst du Schlüssel erstellen. Solange v0 in der Beta ist, können sich Endpunkte und Antwortfelder noch ändern — jede freigegebene Integration wird vorher informiert.

Zuerst lesen: Schreibvorgänge sind asynchron

Ein Schreibvorgang liefert keinen Rang zurück. Er liefert 202 Accepted und ein Handle, denn die API reiht nur einen Befehl ein – die gesamte Wertungsberechnung gehört dem Discord-Bot. Auf einem Board mit Prüffenster bewegt sich in der Rangliste gar nichts, bis ein Moderator in Discord auf Approve klickt, und das kann einen Tag später sein oder nie.

201 Created tritt in genau einem Fall auf: Das Prüffenster des Boards beträgt null Stunden und der Worker war innerhalb der rund drei Sekunden Wartezeit fertig. Ein Timeout antwortet weiterhin mit 202 – behandle also beides.

GET /submissions/{handle} abzufragen ist der einzige richtige Weg herauszufinden, was passiert ist. Eine Integration, die ein erfolgreiches POST als geänderte Rangliste versteht, ist kaputt, bevor sie live geht.

Bevor du Code schreibst

Acht Dinge, die darüber entscheiden, ob eine Integration funktioniert. Keines davon lässt sich aus der Endpunktliste erraten.

Ein Schreibvorgang ist eine Anfrage, kein Ergebnis

POST reiht einen Befehl ein und antwortet mit einem Handle wie sub_88213 und applied: false. Frage das Handle ab und nimm nie an, dass sich die Rangliste bewegt hat.

Wertungen werden beim Einreichen eingefroren

Die Wertung jedes Teilnehmers wird gelesen, wenn das Match erstellt wird, nicht wenn es freigegeben wird. Zehn direkt hintereinander gesendete Matches rechnen alle gegen die Wertungen von vor dem Turnier. Deterministisch, identisch zum Bot – und beim ersten Mal überraschend.

ELO nimmt einen Sieger, League ein Ergebnis

Ein ELO-Board hat kein Punktefeld: Sende winner als team1, team2 oder draw. Ein League-Board trägt team1_score und team2_score und leitet den Sieger selbst ab. Jedes lehnt die Felder des anderen mit einem 422 ab, der den beanstandeten Schlüssel nennt.

Time-Boards nehmen Millisekunden

Als Ganzzahl: 1:30 ist 90000. Sekunden zu senden ist der wahrscheinlichste Integrationsfehler dieser API – deshalb meldet jedes Time-Board score_unit: milliseconds in seinem eigenen Schreibvertrag.

Jede Seite trägt genau team_size

Ein 3v3-Board will drei Teilnehmer pro Seite; alles andere ist ein 422 team_size_mismatch. Die Ausnahme ist ein Board mit fixed_teams: true, bei dem jede Seite genau eine team_id ist – das Match läuft zwischen den beiden Team-Entitäten, nicht zwischen ihren Mitgliedern.

Spieler-IDs haben einen Namensraum

Antworten enthalten discord:198374652000000000, custom:Ava, role:998877 oder team:5, und Pfade wie Filter akzeptieren dieselben Formen. Eine reine Discord-Snowflake funktioniert ebenfalls als Eingabe, eine aus Discord kopierte ID lässt sich also direkt einsetzen.

Jedes POST braucht einen Idempotency-Key

Erforderlich, nicht optional: Ein Timeout ist von einem Fehlschlag nicht zu unterscheiden, und ein blind wiederholter Schreibvorgang ist ein zweites Match im Prüfkanal von jemandem. Derselbe Schlüssel mit demselben Body spielt die gespeicherte Antwort erneut ab; derselbe Schlüssel mit anderem Body ist ein 409. Die Einträge werden mindestens 24 Stunden aufbewahrt — das ist eine Untergrenze, kein Verfallsdatum. Betrachte einen Schlüssel daher als endgültig verbraucht, statt ihn wiederzuverwenden.

Cursor statt Offsets

Eine Rangliste ändert sich zwischen zwei Anfragen, deshalb zählt Offset-Paginierung doppelt. Cursor sind zusammengesetzt – ein Wert plus ein Gleichstandskriterium – sodass eine Seitengrenze mitten in einem Block gleicher Punktzahlen genau dort fortsetzt, statt alle darin zu überspringen. Standardmäßig 50 Zeilen pro Seite, höchstens 200. Behandle next_cursor als undurchsichtig.

Was jeder Board-Typ annimmt

Die Schreibform legt das Board fest, sie wird nie pro Einreichung gewählt. Statt diese Tabelle fest zu verdrahten, frag GET /boards/{board}: Der write-Block antwortet für genau dieses Board, bis hin zum K-Faktor oder den Punkten pro Sieg.

Board-Typ	Endpunkt	Body enthält	Mit 422 abgelehnt	Was die Freigabe bewirkt
Classic	POST /boards/{board}/scores	player, score	team1, team2, winner, team1_score, team2_score	Addiert die eingereichte Punktzahl zur laufenden Summe.
Highscore	POST /boards/{board}/scores	player, score	team1, team2, winner, team1_score, team2_score	Behält den besseren von altem und neuem Wert.
Time	POST /boards/{board}/scores	player, score	team1, team2, winner, team1_score, team2_score	Behält die bessere Zeit gemäß der Sortierung des Boards.
ELO	POST /boards/{board}/matches	team1, team2, winner	team1_score, team2_score, score	Eine Nullsummen-Wertungsänderung für die Teams, plus Sieg, Unentschieden oder Niederlage.
League	POST /boards/{board}/matches	team1, team2, team1_score, team2_score	winner, score	Punkte für Sieg, Unentschieden oder Niederlage, plus die Bilanz.
Rating	—	—	—	Kein Schreib-Endpunkt in v0 – eine Rating-Einreichung braucht einen Bild-Upload.

Authentifizierung

Sende einen Schlüssel aus dem Dashboard als Authorization: Bearer sk_live_.... Jeder Schlüssel ist an genau einen Eigentümer gebunden – einen Discord-Server oder ein Benutzerkonto für persönliche Boards – ein Schlüssel kann also nie das Board eines anderen ansprechen. Ein fremdes Board ist ein 404, nie ein 403: Zu bestätigen, dass es existiert, ließe jeden die Boards anderer Leute aufzählen.

Testschlüssel können nur lesen. Ein sk_test_-Schlüssel bedient jeden Lesezugriff und verweigert jeden Schreib-Scope. Schlüssel werden bei der Erstellung genau einmal angezeigt und nur als Hash gespeichert – geht einer verloren, erstelle einen neuen und widerrufe den alten. Mehrere aktive Schlüssel pro Eigentümer sind erlaubt, Rotation kostet damit keine Ausfallzeit.

Lege einen geheimen Schlüssel niemals in Client-Code ab. Die /v1-Routen senden überhaupt keine CORS-Header, ein Browser kann sie also nicht aufrufen. Das ist Absicht, kein Versäumnis.

curl 'https://api.scoreboards.dev/v1/boards' \
  -H 'Authorization: Bearer sk_live_...'

Scopes

Standardmäßig so wenig Rechte wie möglich: Die Stufe Nur Lesen im Dashboard vergibt die drei Lese-Scopes und sonst nichts, erst Lesen und Schreiben ergänzt matches:write und scores:write. Scopes werden exakt geprüft und schließen einander nicht ein — matches:write gewährt kein matches:read. Die beiden Schreib-Scopes sind getrennt, weil ihre Tragweite unterschiedlich ist: eine fehlerhafte Punkte-Integration bläht ein Board auf, eine fehlerhafte Match-Integration verschiebt die Wertung aller.

Scope	Erlaubt
boards:read	Boards auflisten, den Schreibvertrag eines Boards lesen und ein Schreib-Handle auflösen.
entries:read	Die Rangliste und die Platzierung eines einzelnen Teilnehmers lesen.
matches:read	Match-Historie auf ELO- und League-Boards lesen.
matches:write	Ein ELO- oder League-Match einreihen. Wird einem Testschlüssel nie gewährt.
scores:write	Eine Punktzahl auf einem Classic-, Highscore- oder Time-Board einreihen. Wird einem Testschlüssel nie gewährt.

Endpunkte

Neun Operationen. Jeder Pfad unten ist relativ zur Basis-URL, jede Anfrage braucht einen Bearer-Schlüssel, und jede Antwort, die kein 2xx ist, ist ein Problem-Dokument.

Boards

Boards and their derived write contracts.

get/v1/boards

List every board this key can address

Every board owned by the key's owner, oldest first, with the derived write contract on each. A key is bound to exactly one owner (a Discord guild, or a user for u_ boards) and can never address another owner's board.

Start here: write.endpoint, write.requires and write.rejects tell you what to send without reading any prose, and auto_applies tells you whether a write will ever return 201.

Requires the boards:read scope.

Parameter

Name	Ort	Typ	Beschreibung
limitoptional	query	integer	Page size. Default 50, maximum 200. Out of range is a 422.
cursoroptional	query	string	Opaque cursor. Pass the previous page's `next_cursor` back verbatim, or omit it to start at the top. Cursors are composite `(value, tie-breaker)` so a page boundary inside a block of tied scores resumes mid-tie. A malformed cursor is a 400; cursors are NOT signed, so a hand-built one is accepted and silently starts you at an arbitrary position. Never synthesize one.

Antworten

Status	Beschreibung
200	A page of boards.
400	`invalid_request` at the transport level: a body that is not JSON, a missing or unusable `Idempotency-Key`, a malformed cursor, or a player id that is not one this API issues. A body that parsed but was semantically wrong is a 422 instead.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
data	Board[]
has_more	boolean	True when another page exists. Do not infer it from a short page — a page can be short and still have more.
next_cursor	string \| null	Pass back as `?cursor=`. `null` on the last page. Opaque: never parse it, never build one.

Beispielantwort · 200

{
  "data": [
    {
      "id": "board_1",
      "display_name": "Tuesday Chess",
      "type": "ELO",
      "sort": "desc",
      "team_size": 3,
      "fixed_teams": false,
      "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_1",
      "write": {
        "endpoint": "/v1/boards/board_1/matches",
        "requires": [
          "team1",
          "team2",
          "winner"
        ],
        "rejects": [
          "team1_score",
          "team2_score",
          "score"
        ],
        "operator": "elo",
        "k_factor": 24,
        "start_rating": 1000
      },
      "validation_window_hours": 24,
      "auto_applies": false
    },
    {
      "id": "board_2",
      "display_name": "Sunday League",
      "type": "League",
      "sort": "desc",
      "team_size": 1,
      "fixed_teams": false,
      "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_2",
      "write": {
        "endpoint": "/v1/boards/board_2/matches",
        "requires": [
          "team1",
          "team2",
          "team1_score",
          "team2_score"
        ],
        "rejects": [
          "winner",
          "score"
        ],
        "operator": "league_points",
        "points_win": 3,
        "points_draw": 1,
        "points_loss": 0
      },
      "validation_window_hours": 0,
      "auto_applies": true
    },
    {
      "id": "board_3",
      "display_name": "Speedrun",
      "type": "Highscore",
      "sort": "desc",
      "team_size": 1,
      "fixed_teams": false,
      "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_3",
      "write": {
        "endpoint": "/v1/boards/board_3/scores",
        "requires": [
          "player",
          "score"
        ],
        "rejects": [
          "team1",
          "team2",
          "winner",
          "team1_score",
          "team2_score"
        ],
        "operator": "keep_highest"
      },
      "validation_window_hours": 24,
      "auto_applies": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/boards?cursor=eyJzIjoxMjAwLCJwIjoiMTk4Mzc0NjUyMDAwMDAwMDAyIn0' \
  -H 'Authorization: Bearer sk_live_...'

get/v1/boards/{board}

Get one board and its write contract

Metadata plus the derived, read-only write contract. The operator is fixed by the board's type and sort when it is created — Classic accumulates, Highscore keeps the maximum, Time keeps the minimum, ELO applies a zero-sum delta, League awards points — and cannot be overridden per submission.

Read auto_applies before you build anything: when it is false, every write returns 202 and nothing changes until a moderator approves it in Discord.

Requires the boards:read scope.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.

Antworten

Status	Beschreibung
200	The board.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
id	string	Immutable public id. Use it in every path; it never changes, even when `display_name` does.
display_name	string
type	"Classic" \| "Highscore" \| "Time" \| "ELO" \| "League" \| "Rating"	Decides which write endpoint applies. ELO and League take matches; Classic, Highscore and Time take scores; Rating takes neither in v0.
sort	"desc" \| "asc"
team_size	integer	Participants per side on a match board. Each roster must carry exactly this many — unless `fixed_teams` is true, in which case each side is exactly ONE team entity.
fixed_teams	boolean	True when the board plays fixed team entities against each other. A match then names two `team_id`s, not `2 × team_size` players.
url	string
write	WriteContract \| null	What to POST. `null` on Rating boards, which have no v0 write endpoint.
validation_window_hours	integer	Hours a submission waits for a moderator. `0` auto-applies; `999` means manual review with no countdown.
auto_applies	boolean	True only when `validation_window_hours` is 0. When false, a write returns 202 and NOTHING changes on the leaderboard until a human clicks Approve in Discord.

Beispielantwort · 200

{
  "id": "board_1",
  "display_name": "Tuesday Chess",
  "type": "ELO",
  "sort": "desc",
  "team_size": 3,
  "fixed_teams": false,
  "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_1",
  "write": {
    "endpoint": "/v1/boards/board_1/matches",
    "requires": [
      "team1",
      "team2",
      "winner"
    ],
    "rejects": [
      "team1_score",
      "team2_score",
      "score"
    ],
    "operator": "elo",
    "k_factor": 24,
    "start_rating": 1000
  },
  "validation_window_hours": 24,
  "auto_applies": false
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/boards/board_1' \
  -H 'Authorization: Bearer sk_live_...'

Entries

Ranked standings — one row per participant.

get/v1/boards/{board}/entries

List ranked standings

The leaderboard, best first, cursor-paginated. rank is correct on every page, including a page resumed from a cursor.

ELO boards carry elo; every other type carries score. Rating boards have no ranked entries in v0 (they store one row per submission, not per player) and return a 422 board_type_mismatch.

Requires the entries:read scope.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.
limitoptional	query	integer	Page size. Default 50, maximum 200. Out of range is a 422.
cursoroptional	query	string	Opaque cursor. Pass the previous page's `next_cursor` back verbatim, or omit it to start at the top. Cursors are composite `(value, tie-breaker)` so a page boundary inside a block of tied scores resumes mid-tie. A malformed cursor is a 400; cursors are NOT signed, so a hand-built one is accepted and silently starts you at an arbitrary position. Never synthesize one.

Antworten

Status	Beschreibung
200	A page of standings.
400	`invalid_request` at the transport level: a body that is not JSON, a missing or unusable `Idempotency-Key`, a malformed cursor, or a player id that is not one this API issues. A body that parsed but was semantically wrong is a 422 instead.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
data	Entry[]
has_more	boolean	True when another page exists. Do not infer it from a short page — a page can be short and still have more.
next_cursor	string \| null	Pass back as `?cursor=`. `null` on the last page. Opaque: never parse it, never build one.

Beispielantwort · 200

{
  "data": [
    {
      "rank": 1,
      "player_id": "discord:198374652000000001",
      "player_name": "Ava",
      "last_sub": "2026-07-20T12:00:00.000Z",
      "elo": 1450,
      "wins": 9,
      "draws": 2,
      "losses": 1
    },
    {
      "rank": 2,
      "player_id": "discord:198374652000000002",
      "player_name": "Ben",
      "last_sub": "2026-07-21T12:00:00.000Z",
      "elo": 1200,
      "wins": 4,
      "draws": 1,
      "losses": 4
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoxMjAwLCJwIjoiMTk4Mzc0NjUyMDAwMDAwMDAyIn0"
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/boards/board_1/entries?cursor=eyJzIjoxMjAwLCJwIjoiMTk4Mzc0NjUyMDAwMDAwMDAyIn0' \
  -H 'Authorization: Bearer sk_live_...'

get/v1/boards/{board}/entries/{player_id}

Get one participant's standing

One row of the leaderboard, with its live rank. Use a player_id exactly as an entries response returned it; a bare Discord snowflake also works.

A participant with no row on this board is a 404 — a player who has never submitted has no standing to report.

Requires the entries:read scope.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.
player_iderforderlich	path	string	A namespaced player id as returned by the entries endpoints: `discord:<snowflake>`, `custom:<name>`, `role:<id>` or `team:<id>`. A bare Discord snowflake is also accepted, so a caller can paste one straight in. Anything else is a 400.

Antworten

Status	Beschreibung
200	The standing.
400	`invalid_request` at the transport level: a body that is not JSON, a missing or unusable `Idempotency-Key`, a malformed cursor, or a player id that is not one this API issues. A body that parsed but was semantically wrong is a 422 instead.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
rank	integer	1-based, and correct on every page — a resumed page derives it with a COUNT rather than numbering from 1.
player_id	string	Namespaced: `discord:<snowflake>`, `custom:<name>`, `role:<id>` or `team:<id>`. Pass it back verbatim to `/entries/{player_id}` or `?player=`.
player_name	string
scoreoptional	number \| null
elooptional	number \| null
winsoptional	integer \| null
drawsoptional	integer \| null
lossesoptional	integer \| null
submissionsoptional	integer \| null
last_sub	string \| null	RFC 3339 UTC. `null` when the participant has never submitted.

Beispielantwort · 200

{
  "rank": 1,
  "player_id": "discord:198374652000000001",
  "player_name": "Ava",
  "last_sub": "2026-07-20T12:00:00.000Z",
  "elo": 1450,
  "wins": 9,
  "draws": 2,
  "losses": 1
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/boards/board_1/entries/discord:198374652000000001' \
  -H 'Authorization: Bearer sk_live_...'

Matches

Match history on ELO and League boards, and the asynchronous endpoint that records one. The write returns a handle, not a result.

get/v1/boards/{board}/matches

List match history

Recorded matches, newest first. Only ELO and League boards record matches; on any other type this is a 422 board_type_mismatch pointing you at /entries.

Every participant carries the elo they held when the match was submitted, not when it was approved — so a tournament pushed as ten back-to-back matches shows pre-tournament ratings on all ten.

Requires the matches:read scope.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.
limitoptional	query	integer	Page size. Default 50, maximum 200. Out of range is a 422.
cursoroptional	query	string	Opaque cursor. Pass the previous page's `next_cursor` back verbatim, or omit it to start at the top. Cursors are composite `(value, tie-breaker)` so a page boundary inside a block of tied scores resumes mid-tie. A malformed cursor is a 400; cursors are NOT signed, so a hand-built one is accepted and silently starts you at an arbitrary position. Never synthesize one.
playeroptional	query	string	Only matches this participant took part in. Same namespaced form as `Entry.player_id`; a bare snowflake is accepted. An unusable value is a 400, not an empty list.
statusoptional	query	"pending" \| "approved" \| "rejected" \| "adjusted" \| "set"	Only matches in this review state. `adjusted` and `set` are moderator edits made in Discord.

Antworten

Status	Beschreibung
200	A page of matches.
400	`invalid_request` at the transport level: a body that is not JSON, a missing or unusable `Idempotency-Key`, a malformed cursor, or a player id that is not one this API issues. A body that parsed but was semantically wrong is a 422 instead.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
data	Match[]
has_more	boolean	True when another page exists. Do not infer it from a short page — a page can be short and still have more.
next_cursor	string \| null	Pass back as `?cursor=`. `null` on the last page. Opaque: never parse it, never build one.

Beispielantwort · 200

{
  "data": [
    {
      "id": 2,
      "board": "board_1",
      "team_size": 3,
      "team1": [
        {
          "player_id": "discord:198374652000000001",
          "player_name": "Ava",
          "elo": 1450
        },
        {
          "player_id": "discord:198374652000000002",
          "player_name": "Ben",
          "elo": 1200
        },
        {
          "player_id": "custom:demo_1",
          "player_name": "Demo Player",
          "elo": 1050
        }
      ],
      "team2": [
        {
          "player_id": "discord:198374652000000003",
          "player_name": "Cal",
          "elo": 1200
        },
        {
          "player_id": "discord:198374652000000004",
          "player_name": "Dee",
          "elo": 900
        },
        {
          "player_id": "custom:Ava Custom",
          "player_name": "Ava Custom",
          "elo": 1100
        }
      ],
      "winner": "team2",
      "status": "pending",
      "applied": false,
      "submitted_at": "2026-07-25T10:00:00.000Z",
      "submitted_by": "api"
    },
    {
      "id": 1,
      "board": "board_1",
      "team_size": 1,
      "team1": [
        {
          "player_id": "discord:198374652000000001",
          "player_name": "Ava",
          "elo": 1450
        }
      ],
      "team2": [
        {
          "player_id": "discord:198374652000000002",
          "player_name": "Ben",
          "elo": 1200
        }
      ],
      "winner": "team1",
      "status": "approved",
      "applied": true,
      "submitted_at": "2026-07-24T10:00:00.000Z",
      "submitted_by": "api"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/boards/board_1/matches?cursor=eyJzIjoxMjAwLCJwIjoiMTk4Mzc0NjUyMDAwMDAwMDAyIn0&player=discord:198374652000000001&status=approved' \
  -H 'Authorization: Bearer sk_live_...'

post/v1/boards/{board}/matches

Record an ELO or League match (asynchronous)

Returns 202 Accepted and a handle, not a rank. The match is enqueued for the bot that owns the scoring; on a board with a validation window it then sits in the Discord validation channel until a moderator clicks Approve. Poll GET /submissions/{handle} to learn the outcome.

201 Created happens only on an auto-applying board (auto_applies: true) whose worker finished inside the ~3s wait budget. A timeout still returns 202. Handle both.

The body depends on the board type, and each rejects the other's fields with a 422 naming the offending key:

ELO takes team1, team2 and winner (team1 | team2 | draw). It has no score field.
League takes team1, team2, team1_score and team2_score, and DERIVES the winner from the scoreline. Sending winner is refused.

Each roster must carry exactly the board's team_size participants — except on a board with fixed_teams: true, where each side is exactly ONE team_id and the match is between the two team entities rather than their members. Anything else is a 422 team_size_mismatch.

Ratings are snapshotted when the match is created, not when it is approved.

Requires the matches:write scope and an Idempotency-Key header. sk_test_ keys are read-only.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.
Idempotency-Keyerforderlich	header	string	Required on every POST. A value you generate per logical write (a UUID is ideal) and reuse when you retry. Same key + same body replays the stored response byte for byte; same key + a DIFFERENT body is a 409, so a caller who edits and retries never silently receives the old result. Records are kept for at least 24h — that is a floor, not an expiry, so treat a key as permanently spent rather than recycling one. Omitting the header is a 400 — retrying without one risks a duplicate match in someone's validation channel.

Anfrage-Body application/json

An ELO match or a League match — whichever the board is. The two shapes are mutually exclusive.

Sende genau eine dieser Formen – die, die zum Board passt:

EloMatchBody

Feld	Typ	Beschreibung
team1	Participant[]	min items 1 · max items 8
team2	Participant[]	min items 1 · max items 8
winner	"team1" \| "team2" \| "draw"	Words, not codes. `draw` is a legal outcome and applies the zero-sum ELO delta for a tie.

LeagueMatchBody

Feld	Typ	Beschreibung
team1	Participant[]	min items 1 · max items 8
team2	Participant[]	min items 1 · max items 8
team1_score	integer	min 0 · max 9007199254740991
team2_score	integer	min 0 · max 9007199254740991

ELO, 3v3 (board_1)

Exactly `team_size` participants per side. Mixed forms are fine: members, a custom player, a role.

{
  "team1": [
    {
      "discord_id": "198374652000000001"
    },
    {
      "discord_id": "198374652000000002"
    },
    {
      "name": "Demo Player",
      "custom": true
    }
  ],
  "team2": [
    {
      "discord_id": "198374652000000003"
    },
    {
      "discord_id": "198374652000000004"
    },
    {
      "role_id": "role_998877"
    }
  ],
  "winner": "team1"
}

League, 1v1 (board_2)

Both scores required, integers >= 0. The winner is derived; sending one is a 422.

{
  "team1": [
    {
      "discord_id": "198374652000000001"
    }
  ],
  "team2": [
    {
      "discord_id": "198374652000000002"
    }
  ],
  "team1_score": 3,
  "team2_score": 1
}

ELO on a fixed-teams board

One team entity per side, regardless of `team_size`. A draw is a legal outcome.

{
  "team1": [
    {
      "team_id": "team_5"
    }
  ],
  "team2": [
    {
      "team_id": "team_6"
    }
  ],
  "winner": "draw"
}

Antworten

Status	Beschreibung
201	Applied. Only ever returned by a board with `auto_applies: true` whose worker finished inside the wait budget — `applied` is true and `match` is present.
202	Queued. Nothing has changed on the leaderboard. `applied` is false and stays false until the submission is approved. This is the normal response.
400	`invalid_request` at the transport level: a body that is not JSON, a missing or unusable `Idempotency-Key`, a malformed cursor, or a player id that is not one this API issues. A body that parsed but was semantically wrong is a 422 instead.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
409	The `Idempotency-Key` was already used for a request with a DIFFERENT body, or an identical request is still in flight (that variant carries `Retry-After`). Use a new key for a new request, or resend the original body byte for byte.
413	/v1 accepts at most 64 KB per request. The largest legal body — an 8v8 match — is well under a kilobyte.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
handle	string	Poll `GET /submissions/{handle}` with this. Resolves for 30 days, then 404s. pattern ^sub_\d+$
board	string
status	"queued" \| "processing" \| "pending_review" \| "approved" \| "rejected" \| "failed"	On a 202 this is `queued` (or, rarely, `failed` — the worker ran and threw inside the wait budget); `approved` only on a 201. `pending_review` never appears here: it is what the HANDLE reports once the worker has posted the submission for review. Poll the handle for that.
applied	boolean	True only when the result is already live on the leaderboard. False on every 202.
queued_at	string	RFC 3339 UTC, when the write was enqueued. A replayed response repeats the ORIGINAL value.
matchoptional	MatchRef \| null	Present once the worker has created the match. Absent on a plain 202, which is the normal case.

Beispielantwort · 201

{
  "handle": "sub_88214",
  "board": "board_2",
  "status": "approved",
  "applied": true,
  "queued_at": "2026-07-26T12:00:02.881Z",
  "match": {
    "id": 2,
    "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_2",
    "applied": true
  }
}

Beispielanfrage

curl -X POST 'https://api.scoreboards.dev/v1/boards/board_1/matches' \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 8f14e45f-ea6a-4e2b-9c1a-77c0e4d51a10' \
  -H 'Content-Type: application/json' \
  -d '{"team1":[{"discord_id":"198374652000000001"},{"discord_id":"198374652000000002"},{"name":"Demo Player","custom":true}],"team2":[{"discord_id":"198374652000000003"},{"discord_id":"198374652000000004"},{"role_id":"role_998877"}],"winner":"team1"}'

get/v1/boards/{board}/matches/{match_id}

Get one match with its rosters

One match by its per-board id, with both full rosters. League matches carry team1_score and team2_score; ELO matches have no scoreline and omit both.

Requires the matches:read scope.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.
match_iderforderlich	path	integer	The per-board match number (`Match.id`). Not globally unique.

Antworten

Status	Beschreibung
200	The match.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
id	integer	Per-board match number. Not globally unique; always address it under its board.
board	string
team_size	integer
team1	MatchParticipant[]
team2	MatchParticipant[]
winner	"team1" \| "team2" \| "draw" \| null	On a League board this is DERIVED from the scoreline, never supplied by the caller.
team1_scoreoptional	number \| null	League boards only. Absent on ELO boards, which have no scoreline.
team2_scoreoptional	number \| null	League boards only. Absent on ELO boards, which have no scoreline.
status	"pending" \| "approved" \| "rejected" \| "adjusted" \| "set"	`pending` until reviewed. `adjusted` and `set` are moderator edits made in Discord.
applied	boolean	True only once the result is live on the leaderboard (`approved`, `adjusted` or `set`).
submitted_at	string \| null	RFC 3339 UTC, when the match was submitted — not when it was approved.
submitted_byoptional	string \| null	The Discord user who submitted it, or `api` for a submission made through this API.

Beispielantwort · 200

{
  "id": 2,
  "board": "board_1",
  "team_size": 3,
  "team1": [
    {
      "player_id": "discord:198374652000000001",
      "player_name": "Ava",
      "elo": 1450
    },
    {
      "player_id": "discord:198374652000000002",
      "player_name": "Ben",
      "elo": 1200
    },
    {
      "player_id": "custom:demo_1",
      "player_name": "Demo Player",
      "elo": 1050
    }
  ],
  "team2": [
    {
      "player_id": "discord:198374652000000003",
      "player_name": "Cal",
      "elo": 1200
    },
    {
      "player_id": "discord:198374652000000004",
      "player_name": "Dee",
      "elo": 900
    },
    {
      "player_id": "custom:Ava Custom",
      "player_name": "Ava Custom",
      "elo": 1100
    }
  ],
  "winner": "team2",
  "status": "pending",
  "applied": false,
  "submitted_at": "2026-07-25T10:00:00.000Z",
  "submitted_by": "api"
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/boards/board_1/matches/2' \
  -H 'Authorization: Bearer sk_live_...'

Submissions

Score submissions on Classic, Highscore and Time boards, and resolving the handle that any write returns.

post/v1/boards/{board}/scores

Submit a score to a Classic, Highscore or Time board (asynchronous)

Returns 202 Accepted and a handle, not a new rank. Like every /v1 write it enqueues, and on a board with a validation window the score waits for a moderator. Poll GET /submissions/{handle}.

Time boards take MILLISECONDS as an integer — 1:30 is 90000. This is the most likely integration bug on the whole API; the board's write.score_unit says so too.

What the score does on approval is fixed by the board and is not a caller choice: Classic adds it to the running total, Highscore keeps the higher value, Time keeps the lower one.

ELO and League boards take matches, not scores, and answer 422 board_type_mismatch here.

Requires the scores:write scope and an Idempotency-Key header. sk_test_ keys are read-only.

Parameter

Name	Ort	Typ	Beschreibung
boarderforderlich	path	string	The board id — `metadata.game_name`, e.g. `board_1`. Immutable, and never the display name. Older boards may carry a free-form (even non-ASCII) name, so URL-encode it.
Idempotency-Keyerforderlich	header	string	Required on every POST. A value you generate per logical write (a UUID is ideal) and reuse when you retry. Same key + same body replays the stored response byte for byte; same key + a DIFFERENT body is a 409, so a caller who edits and retries never silently receives the old result. Records are kept for at least 24h — that is a floor, not an expiry, so treat a key as permanently spent rather than recycling one. Omitting the header is a 400 — retrying without one risks a duplicate match in someone's validation channel.

Anfrage-Body application/json

One participant and one integer score.

Feld	Typ	Beschreibung
player	Participant	Exactly one of the four forms. Anything else is a 422 `unknown_player`.
score	integer	Integer. On a Time board this is MILLISECONDS: `1:30` is `90000`, not `90` and not `1.5`. min -9007199254740991 · max 9007199254740991

A Discord member

{
  "player": {
    "discord_id": "198374652000000001"
  },
  "score": 145530
}

A Time board — milliseconds

A run of 2 minutes 25.530 seconds. Sending `145.53` seconds would record 145 ms.

{
  "player": {
    "name": "Ava",
    "custom": true
  },
  "score": 145530
}

Antworten

Status	Beschreibung
201	Applied. Only ever returned by a board with `auto_applies: true` whose worker finished inside the wait budget — `applied` is true and `match` points at the stored submission.
202	Queued. Nothing has changed on the leaderboard. The score waits in the Discord validation channel until a moderator approves it. This is the normal response.
400	`invalid_request` at the transport level: a body that is not JSON, a missing or unusable `Idempotency-Key`, a malformed cursor, or a player id that is not one this API issues. A body that parsed but was semantically wrong is a 422 instead.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
409	The `Idempotency-Key` was already used for a request with a DIFFERENT body, or an identical request is still in flight (that variant carries `Retry-After`). Use a new key for a new request, or resend the original body byte for byte.
413	/v1 accepts at most 64 KB per request. The largest legal body — an 8v8 match — is well under a kilobyte.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
handle	string	Poll `GET /submissions/{handle}` with this. Resolves for 30 days, then 404s. pattern ^sub_\d+$
board	string
status	"queued" \| "processing" \| "pending_review" \| "approved" \| "rejected" \| "failed"	On a 202 this is `queued` (or, rarely, `failed` — the worker ran and threw inside the wait budget); `approved` only on a 201. `pending_review` never appears here: it is what the HANDLE reports once the worker has posted the submission for review. Poll the handle for that.
applied	boolean	True only when the result is already live on the leaderboard. False on every 202.
queued_at	string	RFC 3339 UTC, when the write was enqueued. A replayed response repeats the ORIGINAL value.
matchoptional	MatchRef \| null	Present once the worker has created the match. Absent on a plain 202, which is the normal case.

Beispielantwort · 201

{
  "handle": "sub_88216",
  "board": "board_7",
  "status": "approved",
  "applied": true,
  "queued_at": "2026-07-26T12:00:04.017Z",
  "match": {
    "id": 118,
    "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_7",
    "applied": true
  }
}

Beispielanfrage

curl -X POST 'https://api.scoreboards.dev/v1/boards/board_1/scores' \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 8f14e45f-ea6a-4e2b-9c1a-77c0e4d51a10' \
  -H 'Content-Type: application/json' \
  -d '{"player":{"discord_id":"198374652000000001"},"score":145530}'

get/v1/submissions/{handle}

Resolve a write handle

The only correct way to learn what happened to a write. status moves queued → processing → pending_review → approved | rejected, or failed.

The answer is read from the live match or submission row, not just from the queue, so it keeps up with a moderator approving hours later. Once the row exists, match.id links to it and match.applied says whether it is live on the leaderboard.

Handles resolve for 30 days, then 404. Another owner's handle is an indistinguishable 404, so sequential handles cannot be probed across tenants.

Requires the boards:read scope.

Parameter

Name	Ort	Typ	Beschreibung
handleerforderlich	path	string	The write handle returned by a POST, e.g. `sub_88213`. Resolves for 30 days.

Antworten

Status	Beschreibung
200	The submission state.
401	Missing, malformed, unknown or revoked API key. Present the key as `Authorization: Bearer sk_live_...`. Authentication runs before the rate limiter, so this response carries no `RateLimit-*` headers.
403	The key authenticated but may not do this: it is missing the scope the operation needs, or it is a `sk_test_` key, which is read-only and is never granted a write scope.
404	No such resource for this key's owner. A board that exists but belongs to somebody else returns exactly this, indistinguishable from one that does not exist — confirming existence would let a caller enumerate other people's boards.
422	The request was understood and refused. `code` says which rule: `invalid_request` (schema, including a `.strict()` body naming the unrecognized key), `board_type_mismatch`, `team_size_mismatch`, `duplicate_participant` or `unknown_player`.
429	Per-key token bucket: 600 reads and 60 writes per minute, tracked as separate buckets so a burst of writes cannot starve the polling that watches for their result. Rate limiting is evaluated BEFORE idempotency, so a 429 is never a replay.
500	Something failed on our side. The detail is deliberately generic — quote `request_id`, which joins your report to our log line.

Feld	Typ	Beschreibung
handle	string	pattern ^sub_\d+$
status	"queued" \| "processing" \| "pending_review" \| "approved" \| "rejected" \| "failed"
board	string
match	MatchRef \| null

Beispielantwort · 200

{
  "handle": "sub_88213",
  "status": "approved",
  "board": "board_1",
  "match": {
    "id": 3,
    "url": "https://scoreboards.dev/leaderboards/111222333444555666/board_1",
    "applied": true
  }
}

Beispielanfrage

curl 'https://api.scoreboards.dev/v1/submissions/sub_88213' \
  -H 'Authorization: Bearer sk_live_...'

Datentypen

Die Objekte, aus denen die Antworten oben bestehen. Jeder Feldname und jede Beschreibung stammt aus den Schemata, mit denen die Handler validieren – sie können also nicht von dem abweichen, was die API tatsächlich annimmt und zurückgibt.

Problem

Every /v1 failure, as application/problem+json (RFC 9457). Branch on code, never on title or detail — those are English prose for humans and may be reworded. The API is English-only and ignores Accept-Language.

Feld	Typ	Beschreibung
type	string (uri)	A stable URI for this error class, e.g. `https://scoreboards.dev/errors/board-type-mismatch`.
title	string	Short human summary. Not machine-readable.
status	integer	Repeats the HTTP status code. min 400 · max 599
detail	string	What went wrong with THIS request, naming the offending field where there is one.
instance	string	The path that failed, e.g. `/v1/boards/board_1/matches`.
code	"invalid_request" \| "authentication_failed" \| "permission_denied" \| "not_found" \| "idempotency_conflict" \| "rate_limited" \| "board_type_mismatch" \| "team_size_mismatch" \| "duplicate_participant" \| "unknown_player" \| "board_locked" \| "internal_error"	The machine-readable contract. Stable across rewordings.
request_id	string	Correlation id, also returned as `X-Request-Id`. Quote it to support.

Board

A leaderboard, plus the derived contract for writing to it. id is the immutable game_name slug (board_123), not the display name — renaming a board never changes it.

Feld	Typ	Beschreibung
id	string	Immutable public id. Use it in every path; it never changes, even when `display_name` does.
display_name	string
type	"Classic" \| "Highscore" \| "Time" \| "ELO" \| "League" \| "Rating"	Decides which write endpoint applies. ELO and League take matches; Classic, Highscore and Time take scores; Rating takes neither in v0.
sort	"desc" \| "asc"
team_size	integer	Participants per side on a match board. Each roster must carry exactly this many — unless `fixed_teams` is true, in which case each side is exactly ONE team entity.
fixed_teams	boolean	True when the board plays fixed team entities against each other. A match then names two `team_id`s, not `2 × team_size` players.
url	string
write	WriteContract \| null	What to POST. `null` on Rating boards, which have no v0 write endpoint.
validation_window_hours	integer	Hours a submission waits for a moderator. `0` auto-applies; `999` means manual review with no countdown.
auto_applies	boolean	True only when `validation_window_hours` is 0. When false, a write returns 202 and NOTHING changes on the leaderboard until a human clicks Approve in Discord.

WriteContract

What this board accepts, derived from its type and sort. operator is read-only — it is fixed when the board is created and cannot be overridden per submission.

Feld	Typ	Beschreibung
endpoint	string
requires	string[]	Fields that must be present in the write body.
rejects	string[]	Fields this board type refuses. Sending one is a 422 naming the offending key.
operator	"elo" \| "league_points" \| "accumulate" \| "keep_highest" \| "keep_lowest"	How an approved submission is applied. Derived from the board type and sort; never a caller input.
score_unitoptional	string	Present on Time boards only. Scores are integer MILLISECONDS — `1:30` is `90000`.
k_factoroptional	integer
start_ratingoptional	integer
points_winoptional	integer
points_drawoptional	integer
points_lossoptional	integer

Entry

One participant's standing. elo is present on ELO boards and score on every other type; wins/draws/losses on ELO and League, submissions on Classic, Highscore and Time.

Feld	Typ	Beschreibung
rank	integer	1-based, and correct on every page — a resumed page derives it with a COUNT rather than numbering from 1.
player_id	string	Namespaced: `discord:<snowflake>`, `custom:<name>`, `role:<id>` or `team:<id>`. Pass it back verbatim to `/entries/{player_id}` or `?player=`.
player_name	string
scoreoptional	number \| null
elooptional	number \| null
winsoptional	integer \| null
drawsoptional	integer \| null
lossesoptional	integer \| null
submissionsoptional	integer \| null
last_sub	string \| null	RFC 3339 UTC. `null` when the participant has never submitted.

MatchParticipant

Feld	Typ	Beschreibung
player_id	string
player_name	string
elooptional	number \| null	The rating this participant held when the match was SUBMITTED, not when it was approved. Ten matches pushed back to back all carry pre-tournament ratings.

Match

One recorded match on an ELO or League board. id is old_id — per-board, so match URLs are always board-nested.

Feld	Typ	Beschreibung
id	integer	Per-board match number. Not globally unique; always address it under its board.
board	string
team_size	integer
team1	MatchParticipant[]
team2	MatchParticipant[]
winner	"team1" \| "team2" \| "draw" \| null	On a League board this is DERIVED from the scoreline, never supplied by the caller.
team1_scoreoptional	number \| null	League boards only. Absent on ELO boards, which have no scoreline.
team2_scoreoptional	number \| null	League boards only. Absent on ELO boards, which have no scoreline.
status	"pending" \| "approved" \| "rejected" \| "adjusted" \| "set"	`pending` until reviewed. `adjusted` and `set` are moderator edits made in Discord.
applied	boolean	True only once the result is live on the leaderboard (`approved`, `adjusted` or `set`).
submitted_at	string \| null	RFC 3339 UTC, when the match was submitted — not when it was approved.
submitted_byoptional	string \| null	The Discord user who submitted it, or `api` for a submission made through this API.

MatchRef

The match a write produced, once the worker has created it.

Feld	Typ	Beschreibung
id	integer
url	string
applied	boolean

DiscordParticipant

A real Discord member. Must be 17-20 digits: a shorter id is stored as a CUSTOM player of that name rather than as the member, so it is refused here instead of creating a row nobody owns.

Feld	Typ	Beschreibung
discord_id	string	pattern ^\d{17,20}$

CustomParticipant

A player who is not a Discord member. custom: true is required and explicit — it is what stops a Discord id typed into name from creating a lookalike row. The internal key is built for you.

Feld	Typ	Beschreibung
name	string	min length 1 · max length 100
custom	boolean

TeamParticipant

A fixed team entity. Valid only on a board with fixed_teams: true, one per side.

Feld	Typ	Beschreibung
team_id	string	pattern ^team_\d+$

RoleParticipant

A Discord role competing as a single entity. Guild-owned boards only.

Feld	Typ	Beschreibung
role_id	string	pattern ^role_\d+$

Participant

Exactly one of the four forms. Anything else is a 422 unknown_player.

BoardList

Cursor-paginated. Pass next_cursor back as ?cursor= for the next page.

Feld	Typ	Beschreibung
data	Board[]
has_more	boolean	True when another page exists. Do not infer it from a short page — a page can be short and still have more.
next_cursor	string \| null	Pass back as `?cursor=`. `null` on the last page. Opaque: never parse it, never build one.

EntryList

Cursor-paginated on the composite (score, player_id), so a page boundary that falls inside a block of tied scores resumes mid-tie instead of skipping everyone on that score.

Feld	Typ	Beschreibung
data	Entry[]
has_more	boolean	True when another page exists. Do not infer it from a short page — a page can be short and still have more.
next_cursor	string \| null	Pass back as `?cursor=`. `null` on the last page. Opaque: never parse it, never build one.

MatchList

Cursor-paginated, newest match first.

Feld	Typ	Beschreibung
data	Match[]
has_more	boolean	True when another page exists. Do not infer it from a short page — a page can be short and still have more.
next_cursor	string \| null	Pass back as `?cursor=`. `null` on the last page. Opaque: never parse it, never build one.

EloMatchBody

The body an ELO board takes. An ELO board has no score field, so team1_score, team2_score and score are refused with a 422 naming the key. Each roster carries exactly the board's team_size — or exactly one team_id when fixed_teams is true.

Feld	Typ	Beschreibung
team1	Participant[]	min items 1 · max items 8
team2	Participant[]	min items 1 · max items 8
winner	"team1" \| "team2" \| "draw"	Words, not codes. `draw` is a legal outcome and applies the zero-sum ELO delta for a tie.

LeagueMatchBody

The body a League board takes. League DERIVES the winner from the scoreline, so a caller-supplied winner is refused with a 422 — accepting it would let the caller contradict their own scores. Points come from the board's points_win/points_draw/points_loss.

Feld	Typ	Beschreibung
team1	Participant[]	min items 1 · max items 8
team2	Participant[]	min items 1 · max items 8
team1_score	integer	min 0 · max 9007199254740991
team2_score	integer	min 0 · max 9007199254740991

ScoreSubmissionBody

The body a Classic, Highscore or Time board takes. On a Time board score is integer MILLISECONDS — 1:30 is 90000. Sending seconds is the single most likely integration bug on this API. What happens on approval is fixed by the board: Classic accumulates, Highscore keeps the maximum, Time keeps the minimum.

Feld	Typ	Beschreibung
player	Participant	Exactly one of the four forms. Anything else is a 422 `unknown_player`.
score	integer	Integer. On a Time board this is MILLISECONDS: `1:30` is `90000`, not `90` and not `1.5`. min -9007199254740991 · max 9007199254740991

WriteAccepted

What a POST returns. It is a receipt, not a result: applied is false on every board with a validation window, and stays false until a moderator approves the submission in Discord.

Feld	Typ	Beschreibung
handle	string	Poll `GET /submissions/{handle}` with this. Resolves for 30 days, then 404s. pattern ^sub_\d+$
board	string
status	"queued" \| "processing" \| "pending_review" \| "approved" \| "rejected" \| "failed"	On a 202 this is `queued` (or, rarely, `failed` — the worker ran and threw inside the wait budget); `approved` only on a 201. `pending_review` never appears here: it is what the HANDLE reports once the worker has posted the submission for review. Poll the handle for that.
applied	boolean	True only when the result is already live on the leaderboard. False on every 202.
queued_at	string	RFC 3339 UTC, when the write was enqueued. A replayed response repeats the ORIGINAL value.
matchoptional	MatchRef \| null	Present once the worker has created the match. Absent on a plain 202, which is the normal case.

Submission

The state of a write handle, read from the LIVE row rather than the queue — so it keeps up with a moderator approving or rejecting the match hours after the queue entry finished.

Feld	Typ	Beschreibung
handle	string	pattern ^sub_\d+$
status	"queued" \| "processing" \| "pending_review" \| "approved" \| "rejected" \| "failed"
board	string
match	MatchRef \| null

Fehler

Jeder Fehlschlag eines Endpunkts aus dieser Referenz ist ein RFC-9457-Problem-Dokument mit application/problem+json. Verzweige über code: Er ist der stabile Teil des Vertrags, während title und detail für Menschen geschrieben sind und umformuliert werden können. Einen Sonderfall solltest du abfangen: Eine URL, die auf gar keine Route passt, beantwortet die Plattform und nicht die API — eine authentifizierte Anfrage an einen vertippten Pfad bekommt deshalb einen 404 als reinen Text. Prüfe den Content-Type, bevor du einen Fehler-Body parst.

Die API ist ausschließlich englisch und ignoriert Accept-Language. Das ist Absicht: Eine Fehlermeldung, die zwischen Umgebungen die Sprache wechselt, ist schwerer zu suchen, nicht leichter. Diese Doku ist übersetzt, die API nicht.

Jede Antwort trägt eine X-Request-Id. Nenne sie, wenn du ein Problem meldest – sie verbindet deine Meldung mit unserer Logzeile.

{
  "type": "https://scoreboards.dev/errors/invalid-request",
  "title": "Invalid request",
  "status": 422,
  "detail": "team1_score, team2_score: not allowed on this request",
  "instance": "/v1/boards/board_1/matches",
  "code": "invalid_request",
  "request_id": "req_8f2a1c4d6b90"
}

Code	Status	Wann er auftritt
invalid_request	400 · 413 · 422	Ein Body, ein Query-Parameter oder ein Cursor passte nicht zum Schema; das Detail nennt das beanstandete Feld. Gilt auch für einen Body über 64 KB.
authentication_failed	401	Fehlender, fehlerhafter, unbekannter oder widerrufener Schlüssel.
permission_denied	403	Dem Schlüssel fehlt der Scope – oder es ist ein Testschlüssel und der Scope ist ein Schreib-Scope.
not_found	404	Kein solches Board, kein solcher Eintrag, kein solches Match oder Handle für den Eigentümer dieses Schlüssels. Eine fremde Ressource ist von einer nicht existierenden nicht zu unterscheiden.
idempotency_conflict	409	Derselbe Idempotency-Key wurde mit einem anderen Body wiederverwendet, oder eine identische Anfrage läuft noch.
rate_limited	429	Das Kontingent ist leer. Warte die Sekunden aus Retry-After ab.
board_type_mismatch	422	Richtiger Endpunkt, falsches Board: eine Punktzahl an ein Match-Board, ein Match an ein Punkte-Board oder irgendetwas an ein Rating-Board.
team_size_mismatch	422	Eine Seite trägt nicht genau die team_size des Boards – oder eine Seite auf einem Fixed-Teams-Board nennt etwas anderes als genau ein Team.
duplicate_participant	422	Derselbe Teilnehmer kommt zweimal vor. Geprüft wird nach der Auflösung, role_998877 und die reine Snowflake 998877 zählen also als eine Entität.
unknown_player	422	Ein Teilnehmer ist unbrauchbar: eine Snowflake mit weniger als 17 Ziffern, eine Rolle auf einem Board ohne Discord-Server, ein Team auf einem Board ohne feste Teams oder ein eigener Spieler ohne custom: true.
board_locked	409	Das Board nimmt keine Schreibvorgänge an.
internal_error	500	Bei uns ist etwas schiefgegangen. Versuch es erneut und nenne die request_id, wenn es bleibt.

Ratenbegrenzung

600 Lese- und 60 Schreibvorgänge pro Minute und Schlüssel, als zwei getrennte Token-Buckets – ein Schwall von Schreibvorgängen kann das Abfragen ihres Ergebnisses also nie aushungern. Die Buckets füllen sich kontinuierlich, ein kurzer Schwall ist damit erlaubt und die Dauerrate wird begrenzt.

RateLimit-Reset ist eine Anzahl Sekunden ab jetzt, X-RateLimit-Reset ein Unix-Zeitstempel. Sie beschreiben denselben Moment in verschiedenen Einheiten; wer das eine für das andere hält, baut einen Client, der die API entweder bombardiert oder jahrzehntelang schläft.

Beide Header-Familien werden auf jeder Antwort nach der Authentifizierung gesendet.

Header	Beschreibung
RateLimit-Limit	Requests allowed per minute for this key: 600 read, 60 write. Read and write quotas are separate buckets.
RateLimit-Remaining	Whole requests left in the current bucket.
RateLimit-Reset	DELTA-SECONDS until the quota is whole again. A duration, not a timestamp (IETF draft semantics).
X-RateLimit-Limit	Legacy spelling of `RateLimit-Limit`, same value.
X-RateLimit-Remaining	Legacy spelling of `RateLimit-Remaining`, same value.
X-RateLimit-Reset	The same instant as `RateLimit-Reset`, as a UNIX TIMESTAMP in seconds. Not a delay (legacy semantics).
Retry-After	Delta-seconds to wait before retrying. Sent on 429, and on the 409 that means an identical request is still in flight.
X-Request-Id	Correlation id for this request, echoed on every response including errors. An inbound `X-Request-Id` matching `[A-Za-z0-9._-]{1,64}` is honoured.
X-API-Lifecycle	Always `beta` today. Sent on EVERY /v1 response — including a 401 and a 404 — so a client learns the contract is provisional on its first call, without reading any documentation. The day it stops saying `beta`, the surface has been frozen and breaking changes will require a new version prefix; treat a change in this value as the signal to re-read the changelog.
Idempotent-Replayed	`true` when this response was replayed from a stored idempotency record rather than executed. Only set on POST responses.

Fehlt etwas?

Erzähl uns, was du baust. v0 liefert bewusst nur Lesezugriffe und drei Schreibwege – Board-Erstellung, Saisons, ausgehende Webhooks und das Zurücknehmen von Matches sind alle vertagt, bis ein echter Nutzer danach fragt. Diese eine Anfrage ist mehr wert als unsere Roadmap. Der Beta-Zugang wird nicht hier angefragt, sondern im Bereich API deines Dashboards.

Frag in unserem Discord