Developer notes

Short, and honest about what is finished. What works today, and what does not exist.

Available now — the demo catalogues, as static JSON

The two game systems that ship with Sahul publish their catalogues as plain JSON files.No key, no account, no rate limit. They are sent with no cross-origin headers, so fetch them from a server rather than from a script in another site's page.

• • /sprite-wars-404/catalogue.json — Sprite Wars 404
• • /tdgs/catalogue.json — TDGS, the reference system for developers

⚠️ The shape can change when a catalogue is rebuilt, and there is no versioned path to pin one to, so do not build something fragile on top of them without saying hello first.

Much of the underlying data belongs to publishers and to community projects who gave permission for this use, not for redistribution. Using it to build something is welcome; re-hosting the lot is not. Ask — the answer is usually yes.

Live — the /v1 token API

Bearer-token authenticated, for your own account's data. Create a token inSettings, Tokens (it needs an account with two sign-in routes), pick its scopes, and send it asAuthorization: Bearer sahul_…. Everything a token does is recorded as done by that token, and revoking one cuts it off instantly.

• GET /v1/me — who this token acts for, and its scopes.
• GET /v1/systems?q=chess — search every game system, the library's and user-created, no token needed.
• POST /v1/systems — create a game system (systems:write). If close matches exist you get them back instead of a duplicate; repeat with "confirmDistinct": true if yours is genuinely different. Caps: 10/day, 20 total per account.
• GET /v1/collection · PUT /v1/collection — your collection state (read / collection:write). Keys are <system>/<catalogue>/<id> and the state carries "schema": 2; a write in the old shape is refused, with the reason. Token writes are audited with before-and-after, so "what did my agent do?" always has an answer.

Two things need you, signed in yourself, and are never available to a token whatever its scopes: deleting your account, and changing how you sign in. And tokens cannot create tokens.

The catalogue standard — host one, point a system at it

A game system's catalogue is one JSON file plus the images it hosts itself, intabletop-catalogue/v1 — served from any static host you control, and attached to a system so Sahul (and anything else) can consume it. Two rules carry the whole format: your version names your id set and id changes owe a migration map, and your catalogue hosts its own images — never someone else's CDN. The reference implementation is live at /tdgs/catalogue.json; the spec and hosting instructions are in the repo as docs/CATALOGUE-STANDARD.md.

Not built — MCP

There is no MCP server. An AI assistant reaches your account through the /v1API above, with a token you create, the same way a script does.

Not supported: browser clients for the authenticated API

The authenticated API is for servers, native apps and MCP clients— not for JavaScript running in someone else's web page. No CORS headers are sent on it, so browsers block cross-origin requests, and that is deliberate rather than an oversight.

The reason is narrow and worth stating: enabling CORS on an origin that also serves cookie-authenticated endpoints is a good way to hand every site on the internet the ability to act as your logged-in users. Keeping it off entirely is a guarantee rather than a configuration nobody revisits.

This does not apply to the catalogue JSON above, which is public data with no credentials attached and is fetchable from a browser today. If a genuine browser-client case turns up, get in touch — it is a decision, not a technical wall.

Get in touch

Building something? Say hello atcontact@sahul.net — it is a one-person project and a conversation beats guessing.