Releases & versioning

Every release is a folder that never changes. One document tells you which is newest.

The registry is published as releases, tagged like software: v3.3.0. Each release is uploaded to its own folder on the API, verified, and then listed. Nothing under a release folder is ever edited afterwards.

Find the newest release

/versions.json is the discovery document. It names the newest release of each major version and lists every release with its tag, schema version, release date and the SHA-256 of its registry.json.

{
  "base_url": "https://api.kairosarchive.net",
  "latest": { "v3": "v3.3.0" },
  "releases": [
    { "tag": "v3.3.0", "schema_version": 11, "released_at": "2026-09-12",
      "sha256": "…digest of that release's registry.json…" },
    { "tag": "v3.2.0", "schema_version": 10, "released_at": "2026-09-01", "sha256": "…" }
  ]
}

A release appears here only after the release workflow has downloaded that release's registry.json back from the CDN, checked its digest against the build, and checked that index.json names the release and that a card file and a slug file are served. latest only ever moves forward.

Two ways to address a file

Pin a release

/v3.3.0/cards/C000139.json. The bytes at this path never change. Your app sees the same data until you choose to move. Cache forever.

Follow the alias

/v3/cards/C000139.json answers 302 to the same path under the newest v3 release. Your app always sees current data of a shape it understands. Browsers and fetch follow the redirect on their own; curl needs --location.

Pick pin for reproducibility (a deck builder that must not change under a user mid-session) and the alias for freshness (a bot that answers card questions). Either way, poll /versions.json to know when something new exists.

Breaking changes are a new major

The schema version in versions.json tells you the shape of the data. Additive changes (a new field, a new file) arrive as a new v3 release and the /v3/ alias moves to it. A change that would break an existing reader becomes a new major with its own alias, /v4/, while /v3/ keeps pointing at the last v3 release. Nothing breaks in place.

Verify what you downloaded

Hash the bytes of registry.json and compare with the sha256 listed for that tag in versions.json. Comparing two checksum files proves only that the checksum file arrived. Each release folder also holds a RELEASED marker (the digest and the workflow run that verified it) and a manifest.json with counts and artifact digests. A folder without the marker is a partial upload, not a release.

import hashlib, json, urllib.request

BASE = "https://api.kairosarchive.net"
HEADERS = {"User-Agent": "my-card-tool/1.0 ([email protected])"}

def fetch(url):
    request = urllib.request.Request(url, headers=HEADERS)
    with urllib.request.urlopen(request) as response:
        return response.read()

versions = json.loads(fetch(f"{BASE}/versions.json"))
tag = versions["latest"]["v3"]
release = next(r for r in versions["releases"] if r["tag"] == tag)
root = versions["base_url"].rstrip("/") + "/" + tag

payload = fetch(f"{root}/registry.json")
if hashlib.sha256(payload).hexdigest() != release["sha256"]:
    raise ValueError("registry.json does not match the digest in versions.json")
registry = json.loads(payload)
print(tag, registry["header"]["cards"], "cards")

Links inside the data point at the alias

Cards, printings and sets carry api_url, their own address on the API, and it uses the /v3/ alias. Follow it from any copy, however old, and you reach the current record. If you want to stay on the release you downloaded, build the path under your pinned root instead: {root}/cards/{codex_id}.json.

Mirrors

Every release is also a tagged GitHub release. https://raw.githubusercontent.com/sadkinglabs/sorcery-registry/{tag}/export/registry.json is the same bytes as the API's copy and matches the same digest.

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