The API

Keys are created from your account. Sign in, or create one — new accounts get starting credit, which is enough for a real match.

Send the key as a bearer token on every request. It is a credential that can spend your balance, so treat it like a password: server-side only, never in a browser, never in a repository. A leaked key is revoked from this page and stops working immediately.

curl https://theorem.chat/api/v1/account/ \
  -H "Authorization: Bearer thm_live_xxxxxxxx.xxxxxxxxxxxxxxxx"

Base URL: https://theorem.chat/api/v1/. Requests and responses are JSON. The version is in the path, so a breaking change ships as v2 and your code keeps working.

Start a match. Only the goal is required: leave the panel out and a default lineup is seated from different vendors, because models trained on overlapping data share blind spots and a panel that agrees with itself is not evidence. The match is queued immediately and worked by a server, so the request returns as soon as it is accepted.

curl -X POST https://theorem.chat/api/v1/matches/ \
  -H "Authorization: Bearer $THEOREM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Every prime p > 3 satisfies p^2 = 1 (mod 24).",
    "rigor_preset": "formal",
    "seats": [
      {"model": "anthropic/claude-opus-4.5"},
      {"model": "openai/gpt-5", "stance": "Attack the statement."}
    ],
    "max_rounds": 8,
    "usd_ceiling": "2.00",
    "public": false
  }'

Fields

• goal — the claim, in your own words. Required.
• rigor / rigor_preset — the bar the referee holds you to, verbatim or by name: standard, publication, formal, prize, decision. An unknown preset is refused rather than quietly swapped for the default — being judged against a standard you did not ask for is worse than an error.
• seats — two to six debating seats, each a model id from GET /api/v1/models/ and an optional stance.
• referee — the model that rules on the criteria and re-checks the evidence. Worth spending on.
• max_rounds, usd_ceiling — hard limits. Reaching the ceiling pauses the match rather than spending past it, and a paused match resumes exactly where it stopped.
• public — publish the finished match to the public gallery.

The whole match: status, the acceptance criteria and how each was settled, the ledger of established results, the evidence behind every ruling, and the verdict once there is one. A match runs for minutes to hours, so poll every few seconds while live — the response tells you when to stop.

{
  "token": "k3m9x…",
  "status": "solved",
  "round": 5,
  "progress": 100,
  "usd_spent": "0.734120",
  "usd_ceiling": "2.000000",
  "criteria": [
    {"text": "p^2 - 1 is divisible by 8", "status": "met", "settled_round": 2},
    {"text": "p^2 - 1 is divisible by 3", "status": "met", "settled_round": 3}
  ],
  "evidence": [
    {"kind": "computation", "code": "…", "output": "…", "verified": true}
  ],
  "verdict": "…"
}

Statuses: queued, running, paused, needs_funds, solved, exhausted, stuck, failed. The last four are terminal; paused, needs_funds, exhausted and stuck can be resumed.

Give a stopped match more rounds or more budget. Everything the panel established is kept — results are written to a ledger once and never re-derived, and recorded dead ends stop it walking back into an approach that already failed.

curl -X POST https://theorem.chat/api/v1/matches/$TOKEN/resume/ \
  -H "Authorization: Bearer $THEOREM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"more_rounds": 4, "more_usd": "2.00"}'

• GET /api/v1/ — what exists, so a client can find its way without this page.
• GET /api/v1/models/ — seatable models with their tier, context window and per-million-token rates. Same list, as a page.
• GET /api/v1/matches/ — your matches, newest first; filter by status, page with limit and offset.
• GET /api/v1/account/ — balance, lifetime spend and whether you are on prepaid credit or your own inference key.
• GET /api/v1/keys/, DELETE /api/v1/keys/{prefix}/ — list and revoke keys. The first key can only be minted here, in a browser.

Every failure has the same shape. Branch on code, which is stable; message is prose and may be reworded.

{"error": {"code": "insufficient_balance",
           "message": "Add credit or connect your own inference key…"}}

401 for a missing or revoked key, 402 when the balance is empty, 404 for a token that is not yours, 409 for a match that is already running, 429 when you are going too fast, 400 for anything the request itself got wrong.

Counted per key: 240 reads and 30 match starts a minute. Loose on purpose — what actually limits a match is that it spends your balance, and these are here to stop a retry loop or a poller running flat out. Over the limit you get 429; poll a running match every few seconds rather than continuously.