Overview & rules

A free, read-only JSON API for Sorcery: Contested Realm. No key, no account, no server-side search.

Kairos Archive publishes the Sorcery Card Registry as JSON files on a CDN. Every card, every printing, every set and the history of every change has a permanent address. There is nothing to sign up for. Read this page once and you know the rules.

Where the API lives

Base URL: https://api.kairosarchive.net
Format: JSON, UTF-8. Card names and rules text contain characters outside ASCII (arrows, accents), so read the bytes as UTF-8.
Methods: GET, HEAD and OPTIONS. The API is read-only: any other method is refused with 403.
Start here: /versions.json names the newest release. The bare domain redirects there too.

Always use https://. The files are static, so there are no query parameters: anything after ? is ignored.

Required headers

Scripts and apps must send a User-Agent that names the project and gives a way to reach you, for example my-card-tool/1.0 ([email protected]). Requests from automated clients with no User-Agent at all are refused with 403. Do not let an HTTP library leave it empty.

Browsers send their own User-Agent, so page JavaScript needs nothing extra. No Accept header is needed: every file is JSON.

Rate limits

JSON files are limited to 30 requests per 10 seconds per IP address. Over that, the edge answers 429 for 10 seconds, then lets you through again. Images are not limited.

The limit is a tripwire against fetching cards one by one, not a quota. A client that downloads the whole database once, or reads an index file, never meets it. A client that looks up one card at a time never meets it either. What trips it is resolving a whole deck by fetching each card's file from one server at once: fetch index/cards.json instead, one request.

Caching

A release root such as /v3.3.0/ is immutable: the bytes at a path never change. It is served with a one-year immutable cache header. Cache it forever.
/versions.json is cached for 60 seconds. Checking it once an hour is plenty; the data changes a few times a year.
Every file carries an ETag. Send If-None-Match and you get 304 Not Modified instead of the file again.

The one rule that matters

For anything beyond a single lookup, download registry.json once and query your copy. It is one file with everything in it, about 6 MB stored and a fraction of that over the wire. Poll /versions.json to learn when a new release exists. Please do not crawl the per-object files. Download the data walks through it.

Look up one card

Both examples follow the /v3/ alias, which redirects to the newest v3 release. fetch follows the redirect on its own; curl needs --location.

Browser · fetch one card

const response = await fetch("https://api.kairosarchive.net/v3/cards/C000139.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const card = await response.json();
console.log(card.name, card.rules_text);

curl · the same card

curl --fail --location \
  --user-agent 'my-card-tool/1.0 ([email protected])' \
  'https://api.kairosarchive.net/v3/cards/C000139.json'

Open Askelon Phoenix as JSON →

Mirrors and availability

The domain is a CDN in front of object storage, with no maintenance windows and no SLA. Every release is also a tagged GitHub release: https://raw.githubusercontent.com/sadkinglabs/sorcery-registry/{tag}/export/registry.json, the same bytes. Because identifiers never change, a copy you already hold is never wrong, only older.