REST API

Read tokens and releases, propose changes and manage themes and webhooks over HTTPS. Every call runs as the key's owner, inside their roles.

Authentication

Create a key in Settings > API keys and send it as a bearer token. Keys act as you; revoke them at any time.

Terminal
curl -H "Authorization: Bearer $STOAKEN_API_KEY" https://stoaken.com/api/brands

Versions

Pin a version with the Stoaken-Version header (current: 2026-09-29). Responses echo the version they used.

Rate limits

120 requests per minute per key, and 60 writes per hour. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit you get 429 with Retry-After.

Idempotency

Send an Idempotency-Key header on writes. Repeating the same request with the same key returns the first response (with Idempotent-Replayed: true) instead of doing it twice.

Errors

Errors are RFC 9457 problem documents (application/problem+json) with a type you can look up at /api/problems/<slug> and a plain detail. On the Free plan, writes return 403 with what to upgrade.

Endpoints

The full schema is at /api/openapi.json (OpenAPI 3.1). Lists are paginated with limit and cursor.

MethodPathKind
GET/api/brandsRead
GET/api/brands/:brandIdRead
GET/api/brands/:brandId/token-setsRead
GET/api/brands/:brandId/themesRead
POST/api/brands/:brandId/themesWrite
GET/api/token-sets/:tokenSetIdRead
PUT/api/token-sets/:tokenSetId/documentWrite
PATCH/api/token-sets/:tokenSetId/tokensWrite
GET/api/themes/:themeIdRead
PATCH/api/themes/:themeIdWrite
DELETE/api/themes/:themeIdWrite
GET/api/themes/:themeId/tokensRead
GET/api/themes/:themeId/tokens/rawRead
GET/api/themes/:themeId/deprecationsRead
POST/api/themes/:themeId/deprecationsWrite
GET/api/themes/:themeId/releasesRead
GET/api/themes/:themeId/exportRead
POST/api/themes/:themeId/releasesWrite
GET/api/releases/:releaseIdRead
GET/api/releases/:releaseId/snapshotRead
GET/api/releases/:releaseId/exportRead
POST/api/releases/:releaseId/submitWrite
GET/api/brands/:brandId/webhooksRead
POST/api/brands/:brandId/webhooksWrite
PATCH/api/webhooks/:webhookIdWrite
DELETE/api/webhooks/:webhookIdWrite
POST/api/webhooks/:webhookId/rotate-secretWrite
POST/api/webhooks/:webhookId/pingWrite
Propose a release
curl -X POST https://stoaken.com/api/themes/$THEME_ID/releases \
  -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Idempotency-Key: release-1-4-0" \
  -H "Content-Type: application/json" \
  -d '{"version":"1.4.0"}'