Endpoints & releases

One immutable snapshot per release. One discovery document to find it.

Find the release

https://api.kairosarchive.net/versions.json contains base_url, latest by major version, and a releases array. Each entry includes its tag, schema version, release date and the digest of registry.json.

Follow updates: /v3/… redirects with HTTP 302 to the newest verified v3 release.
Pin a snapshot: Read a tag from discovery and use /{tag}/…. All requests using that root stay on the same snapshot.
Breaking changes: A new major gets its own alias. Follow the major your client understands.

Discovery is cached for 60 seconds. Checking hourly is sufficient for typical clients. Immutable release files have a one-year immutable cache policy and their bytes never change. Images have their own permanent, content-addressed URLs.

Available files

These paths are relative to a release root or the /v3/ alias. They are static files; search expressions and query parameters do not filter their contents.

Path	Response
`index.json`	Discovery for this root: schema and dataset versions, counts, endpoint templates and terms.
`registry.json`	The entire committed export: cards, printings, sets and all three histories.
`registry.json.sha256`	SHA-256 in sha256sum format. Verify the downloaded export bytes.
`schema.json`	The full export JSON Schema, draft 2020-12.
`cards/{codex_id}.json`	Card fields plus printing summaries, name_history and card_history.
`printings/{printing_id}.json`	Printing fields plus slug_history.
`slugs/{slug}.json`	Resolve a current or historical slug to permanent card and printing IDs.
`sets.json`	The set catalogue array.
`sets/{set_code}.json`	A set record with a cards array of names, IDs and that set’s printing IDs.
`index/cards.json`	Compact card records for local search and filtering.
`index/printings.json`	Compact printing records with image_hash and image_status.
`index/slugs.json`	An object mapping every known slug to its printing_id.
`history/cards.json`	All recorded gameplay faces.
`history/names.json`	Every recorded card name and its registry validity range.
`history/slugs.json`	Every recorded slug and its registry validity range.

Make a request

curl · follow the release redirect

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

Check the HTTP response before parsing JSON. An unknown slug returns 404; retired printings remain in the registry. Fetch bulk exports or indexes for large imports rather than requesting every object separately.

Links can leave a snapshot

api_url on full card, printing and set records points to the moving major alias. Following it from a historical release opens the current record. To stay on your selected release, construct the documented path under your pinned root instead. kairos_url links to the website.

The compact indexes contain selected fields, not full objects. In the current publisher implementation they do not include api_url or kairos_url; use the documented ID paths for lookups.

Full export versus object responses

The full export separates entities and histories into arrays. A card object adds that card’s history and printing summaries. A set entry in sets.json has a numeric cards count; the individual set object replaces that field with an array of its cards.

Release verification and mirrors

A verified root includes a RELEASED marker; release builds also include a manifest. Verify the actual registry.json bytes against the discovery digest. Comparing two checksum strings alone does not verify your download.

If you already know a release tag, its export is also available from https://raw.githubusercontent.com/sadkinglabs/sorcery-registry/{tag}/export/registry.json. Verify it against the same expected digest.

Reference: registry API contract and published object definitions. Report a data or documentation issue.