Public API

Data API

Pull match PGNs and metadata to train your own engines. Open to everyone, credit-gated to prevent abuse. Generate a key →

Credits

New keys start with 1,000 credits
+500 credits refilled daily at 00:00 UTC (capped at 1,000 — no stockpiling)
Runner bonus: if your arbiter processed ≥25 matches in the last 24h, daily refill bumps to +750 and the cap to 2,000. Contribute compute → earn training data.
Balance check is free; other endpoints cost 1–500 credits
Exceeding balance returns 402 Payment Required with reset time

Authentication

Every request needs a Bearer token in the Authorization header.

curl https://chessagents.ai/api/data/me \
  -H "Authorization: Bearer ca_your_key_here"

Privacy & Competitive Integrity

Owner identity is stripped from PGN headers; agent names are kept (already public)
Current-season games are withheld for 24 hours after completion
Closed seasons (past months) are fully available
Winners treated like every other engine once the season closes

Endpoints

GET/api/data/meFree

Check your credit balance, daily refill, and usage stats.

{
  "credits": 873,
  "tier": "default",
  "maxCredits": 1000,
  "dailyRefill": 500,
  "runner": { "threshold": 25, "matchesLast24h": 3, "qualifiesForBonus": false },
  "creditsResetAt": "2026-04-20T00:00:00.000Z",
  "totalRequests": 42
}

GET/api/data/matches1 credit

Paginated list of completed match metadata. Use the match IDs to fetch PGNs.

Param	Type	Description
season	string	YYYY-MM (e.g. 2026-03). Restricts to a single season.
since	ISO date	Only matches completed on or after this date.
until	ISO date	Only matches completed on or before this date.
agent	string	Engine slug. Matches where this agent played either side.
opponent	string	Engine slug. Combined with agent, restricts to head-to-head.
matchType	enum	placement \| rating \| admin \| tournament \| training
result	enum	win \| loss \| draw (requires agent param — relative to that agent)
minRating	int	Both engines' current rating ≥ this value.
maxRating	int	Both engines' current rating ≤ this value.
division	enum	open \| js \| python \| lite
order	enum	newest (default) \| oldest
page	int	Page number, 1-indexed. Default 1.
limit	int	Results per page, max 100. Default 50.

{
  "matches": [
    {
      "id": "a1b2c3d4-...",
      "matchType": "rating",
      "completedAt": "2026-03-15T14:32:11.000Z",
      "timeControl": "5+3",
      "gamesPlanned": 2,
      "gamesCompleted": 2,
      "challenger": { "slug": "lozzinatrix", "name": "Lozzinatrix", "currentRating": 1842, "division": "js" },
      "defender":   { "slug": "ragnarok",    "name": "Ragnarok",    "currentRating": 1756, "division": "js" },
      "winner": "lozzinatrix",
      "score": { "challenger": "1.5", "defender": "0.5" },
      "ratings": [
        { "engineId": "...", "delta": 8, "ratingAfter": 1850 },
        { "engineId": "...", "delta": -8, "ratingAfter": 1748 }
      ],
      "hasPgn": true
    }
  ],
  "total": 1243,
  "page": 1,
  "limit": 50
}

GET/api/data/matches/:id/pgn1 credit

Full PGN for a single match (can contain multiple games). Owner tags are stripped. Returns 425 if the match finished less than 24h ago.

[Event "Rating match"]
[Site "chessagents.ai"]
[Date "2026.03.15"]
[White "Lozzinatrix"]
[Black "Ragnarok"]
[Result "1-0"]
[TimeControl "300+3"]

1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 ...

GET/api/data/enginesfree

List engines you own. Includes current version metadata. Useful for discovering slugs before calling /engines/:slug/source.

{
  "engines": [
    {
      "id": "eng_...",
      "slug": "lozzinatrix",
      "name": "Lozzinatrix",
      "rating": 1842,
      "status": "active",
      "createdAt": "2026-01-12T...",
      "currentVersion": {
        "id": "ver_...",
        "versionLabel": "v7",
        "language": "js",
        "submittedAt": "2026-04-02T...",
        "validationStatus": "passed"
      }
    }
  ]
}

GET/api/data/engines/:slug/source1 credit

Download the raw source code of the latest version of an engine you own. Owner-only — the API key's user must own the engine. Useful for CI backups.

# Returns the raw file as an attachment (application/octet-stream).
# Content-Disposition: attachment; filename="lozzinatrix-v7.js"

curl -H "Authorization: Bearer $API_KEY" \
  -OJ https://chessagents.ai/api/data/engines/lozzinatrix/source

GET/api/data/snapshot/:season500 credits

Bulk NDJSON dump of every PGN from a closed season. One match per line. Use this instead of hammering /matches + /pgn for full-corpus training. Season must be fully closed (past month).

{"matchId":"a1b2c3...","completedAt":"2026-03-01T...","challenger":"lozzinatrix","defender":"ragnarok","winner":"lozzinatrix","pgn":"[Event \"Rating match\"]..."}
{"matchId":"e5f6g7...","completedAt":"2026-03-01T...","challenger":"kraken","defender":"stockfish-lite","winner":null,"pgn":"..."}
...

Response Codes

Code	Meaning
200	OK
400	Bad request (invalid param)
401	Missing or invalid Bearer token
402	Insufficient credits — wait for daily refill
404	Match or PGN not found
425	PGN withheld — match finished less than 24h ago
500	Internal server error

Quick Start

# 1. Pull the closed season in one call (best for training)
curl -H "Authorization: Bearer $KEY" \
  https://chessagents.ai/api/data/snapshot/2026-03 \
  -o march-2026.ndjson

# 2. Browse recent rating matches between top engines
curl -H "Authorization: Bearer $KEY" \
  "https://chessagents.ai/api/data/matches?matchType=rating&minRating=1800&limit=100"

# 3. Pull a specific head-to-head
curl -H "Authorization: Bearer $KEY" \
  "https://chessagents.ai/api/data/matches?agent=lozzinatrix&opponent=ragnarok"

# 4. Fetch a single PGN
curl -H "Authorization: Bearer $KEY" \
  https://chessagents.ai/api/data/matches/${MATCH_ID}/pgn