Developer notes

Short, and honest about what is finished. One thing works today; the rest is designed and building.

Available now — the catalogue, as static JSON

The catalogue is served as plain JSON from the CDN. No key, no account, no rate limit, and it sends Access-Control-Allow-Origin: *, so you can fetch it from a browser as well as a server.

• • /data/units.json — every unit
• • /data/products.json — releases and products
• • /army-data/index.json — factions, and one file per faction

⚠️ These are unversioned build artefacts. The shape can change when the catalogue is rebuilt. A versioned path is planned for anyone who needs to pin one — until then, 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 onyour profile (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). 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.

Being built — MCP

A remote MCP server wrapping the same operations as /v1, so an AI assistant can connect directly with OAuth instead of a pasted token. The API above is the same surface it will expose — build against it now and the MCP adds a transport, not a new contract.

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.