Build on Stoaken

01 · HTTP

REST API

Read Brands, token sets, themes and releases, save token documents, propose releases and deprecations. Create an API key under Settings → API keys and send it as a Bearer token.

• Pin the version with the Stoaken-Version: 2026-09-29 header.
• Writes need an Idempotency-Key header, so a retried request never applies twice.
• Lists are paged with a cursor: pass back next_cursor as returned.
• Errors use the standard problem format (RFC 9457) with a stable type for each kind of problem.
• Limits: 120 requests a minute and 60 writes an hour per credential, reported in RateLimit-* headers.
• The full reference is an OpenAPI 3.1 document at /api/openapi.json.

curl -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Stoaken-Version: 2026-09-29" \
  https://stoaken.com/api/brands

# Nothing is published: a person approves it.
curl -X POST -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-2026-10-06" \
  -d '{"version":"1.4.0"}' \
  https://stoaken.com/api/themes/THEME_ID/releases

There is deliberately no endpoint to approve or publish. That happens in the Command Center, by a person.

Export tokens as code

Get a theme's live release as a file, ready to commit. The output has no timestamps, so a new export only shows up in a diff when the tokens changed. Pick a format with format:

• cssCSS variablesA custom property for every token. Modes become attribute selectors, so one file covers them all.
• json-dtcgJSON (W3C)Resolved tokens in the W3C 2025.10 format, for Style Dictionary v5 and other current tools. One mode per file.
• json-sd4JSON (Style Dictionary v4)The same tokens with the older value format Style Dictionary v4 reads: hex colours, "16px", "200ms". One mode per file.
• jsJavaScriptAn ES module exporting a nested object of CSS-ready values. One mode per file.
• tsTypeScriptThe JavaScript module, typed with as const so values autocomplete. One mode per file.

curl -H "Authorization: Bearer $STOAKEN_API_KEY" \
  "https://stoaken.com/api/themes/THEME_ID/export?format=css&prefix=acme" \
  -o tokens.css

CSS puts every mode in one file: the default under :root, the others as attribute selectors such as [data-color-scheme="dark"]. The other formats hold one mode per file; pass mode for a non-default one. To preview a release that's still waiting for review, export it by id: /api/releases/RELEASE_ID/export. Anything that can't be written faithfully (a gradient in CSS, for example) is left out and explained in the file's header, and counted in the Stoaken-Export-Warnings header.