Developers
clth.fyi is readable without JavaScript. Item pages include JSON-LD, Markdown twins at /s/{code}.md, and a public JSON API. Agents can also call the read-only MCP endpoint.
Public API
Base path /api/v1. Every record includes source_url
and updated_at. Errors are JSON:
{"error":{"code":"not_found","message":"No item with that code."}}
Public reads send Access-Control-Allow-Origin: *. Too many requests return
429
and Retry-After.
GET /api/v1/items/:codeGET /api/v1/items/:code/provenanceGET /api/v1/designsGET /api/v1/designs/:id
Private items omit the owner name, specs, and email. Emails are never in a public payload.
Machine-readable contract: /openapi.json. Markdown twin of this page: /developers.md.
Maker API
Send Authorization: Bearer clth_…. Mint a token from the dashboard. Stripe is off unless
STRIPE_SECRET_KEY
is set. Import buyers with a CSV when you sell somewhere else.
POST /api/v1/designs-
POST /api/v1/batcheswithdesign_id,quantity, optionalsizes GET /api/v1/batches/:idandGET /api/v1/batches/:id/items-
POST /api/v1/orderswithexternal_order_idandbatch_idordesign_id. Repeating the order id returns the same code. GET /api/v1/orders/:external_order_idPOST /api/v1/importswith a CSV body-
GET /api/v1/analyticsand/analytics/batches/:idand/analytics/items/:code
Print files, no auth, no PIN: /q/{code}.svg, .png, .pdf.
MCP
Streamable HTTP at /mcp. Initialize, then call tools. Every tool is annotated readOnlyHint: true.
get_item— public facts for a codeverify_ownership— does this public name match the current ownerget_provenance— the append-only loglist_designs— public designsget_item_stats— public scan counts only
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:4471/mcp --method tools/list
Scan URL
Codes are uppercase Crockford base32, 7 characters plus a check character.
The QR payload is HTTPS://CLTH.FYI/S/
plus the code: 27 characters, alphanumeric mode, error correction Q, 4-module quiet zone.