Developer API

Upload matches to a Tarnished's Ledger account from your own tools. Authenticate with a personal API key; each import is written to your account. Create & manage keys on the Developers page (sign in required).

Endpoint

POST https://tarnishedledger.com/api/import/match
Authorization: Bearer rtm_…
Content-Type: application/json

Example

curl -X POST https://tarnishedledger.com/api/import/match \
  -H "Authorization: Bearer rtm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-tool-match-0001",
    "date": "2026-06-14",
    "format": "Lion Locked",
    "matchType": "1v1",
    "matchClass": "casual",
    "outcome": "win",
    "condition": "bingo",
    "gameVersion": "dlc",
    "opponents": [{ "name": "RivalPlayer", "account": "rivalplayer", "gameVersion": "base" }],
    "weapon": "Rivers of Blood",
    "board": [
      { "position": 0, "text": "Kill Margit", "state": "mine", "markedAtSeconds": 95 }
      /* …25 cells total… */
    ]
  }'

Body fields

• date — YYYY-MM-DD (required).
• matchType — 1v1 or 2v2 (required).
• outcome — win | loss (required).
• condition — bingo | majority | bingority | forfeit | timeout (required).
• opponents — array; exactly 1 (1v1) or 2 (2v2). Each: name (shown), optional account (a Ledger username to tag — the match then appears on their profile too), optional gameVersion.
• teammate — required for 2v2 (same shape as an opponent).
• format — a format name or id (must be public or yours). Optional.
• weapon — exact weapon catalog name. Optional.
• gameVersion — yours: base | dlc | both (default base).
• matchClass — casual (default) | practice | official; tournamentName free-text for official.
• myScore / oppScore / durationSeconds — optional (scores are derived from the board if omitted).
• board — empty, or exactly 25 cells: position 0–24, text, state (none|mine|opp), optional markedAtSeconds.
• id — optional stable id. Re-importing the same id is idempotent (returns the existing match instead of duplicating).

Tournament / neutral imports

With a key that has the tournament scope you can record a game between two OTHER players (a “neutral” match) for a tournament you organise. You must be the tournament’s owner, admin, or ref. Both players are tagged, so it lands on both their profiles; it doesn’t count toward your own stats.

• neutral: true + tournamentId (required) + optional pairingId.
• team1 / team2 — arrays of { account, name?, gameVersion? }; 1 player each (1v1) or 2 (2v2). account is required (a real Ledger username). outcome is team1’s result.
• Omit opponents/teammate for neutral imports.

Responses & limits

• 201 { ok: true, id } created · 200 { ok: true, id, deduped: true } already imported.
• 401 bad/revoked key · 400 malformed body · 403 missing scope / not an organiser · 413 body over 256 KB · 422 a reference (format/weapon/account) didn't resolve · 429 rate limited.
• Rate limit: 60 imports per minute per user. Imported matches don't notify tagged players.
• Keys are revocable any time and expire from disuse. Treat a key like a password — it can write matches as you.