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.
• css-autoCSS, light and darkLight values in :root and dark values inside prefers-color-scheme: dark, so the page follows the device. data-theme="light" or "dark" on <html> overrides it.
• 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.
• scssSCSSA Sass variable for every token, with CSS-ready values. One mode per file.
• tailwindTailwind configA tailwind.config.js theme.extend with colors, spacing, fonts, shadows and easing. Works with Tailwind 3, and Tailwind 4 through @config. One mode per file.
• tailwind4Tailwind 4 themeA CSS file with an @theme block (--color-*, --spacing-*, --font-*, --shadow-*, --ease-*, --radius-*) for Tailwind 4. Import it after "tailwindcss". One mode per file.
• swiftSwift (SwiftUI)A StoakenTokens enum with Color, CGFloat, Font.Weight and TimeInterval constants. One mode per file.
• composeJetpack ComposeA Kotlin StoakenTokens object with Color, Dp, FontWeight, TextStyle and easing values for Compose. One mode per file.
• androidAndroid XMLA values resource file with colors, dimens (dp), integers and strings. One mode per file, e.g. values/ and values-night/.

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.