Developers

Build on Stoaken

A REST API, an MCP server for AI agents, signed webhooks and a CLI. Every call runs as a person, inside their role, and every change goes through review.

requests per key
120/min
API version
v2026-09-29
ways to skip review
0
curl -X POST https://www.stoaken.com/api/themes/THEME_ID/releases \
  -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Stoaken-Version: 2026-09-29" \
  -H "Idempotency-Key: ship-1-4-1" \
  -d '{"version":"1.4.1"}'

Response

201 Created
{ "id": "rel_8f2c", "version": "1.4.1",
  "status": "pending_approval",
  "changes": { "changed": 3, "added": 1, "breaking": false } }

The loop

From a proposal to your build, with a person in the middle

Automate everything around the decision, never the decision itself.

  1. 01ProposeAn agent, a script or a person sends a change: MCP, REST or the CLI.
  2. 02ResolveStoaken works out every mode and what the change reaches, with visual checks.
  3. 03ApproveA person with the right role says yes. There is no API for this step.
  4. 04ShipA signed webhook tells your build; it exports the new tokens as code.

01 · HTTP

REST API

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

  • VersionedPin Stoaken-Version: 2026-09-29; old versions keep working.
  • Idempotent writesEvery write takes an Idempotency-Key: a retry never applies twice.
  • Cursor pagingPass back next_cursor as returned; no page drift.
  • Clear errorsRFC 9457 problem details with a stable type for each kind of problem.
  • Fair limits120 requests a minute, 60 writes an hour per key, in RateLimit-* headers.
  • DescribedOpenAPI 3.1 at /api/openapi.json, for generators and agents.
curl -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Stoaken-Version: 2026-09-29" \
  https://www.stoaken.com/api/brands
# A person approves it (or, with velocity on, it goes live if it breaks nothing).
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://www.stoaken.com/api/themes/THEME_ID/releases

56 endpoints · read from the route table, so always current

There is deliberately no endpoint to approve or publish. The full reference is OpenAPI 3.1 at /api/openapi.json.

Export tokens as code

Get a theme’s live release as a file, ready to commit. Pick a format to see what you’d get: this is real output from the exporter, for a six-token sample with light and dark modes.

CSS variables

A custom property for every token. Modes become attribute selectors, so one file covers them all.

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

No timestamps in the output, so a new export only shows in a diff when the tokens changed. What a format can’t say faithfully is left out and explained in the header.

/**
 * Acme, Default theme, v1.4.0 (live).
 * Generated by Stoaken. Don't edit by hand: propose changes in Stoaken, then export again.
 *
 * Modes:
 * - color-scheme: light (default), dark. Switch with data-color-scheme="dark" on <html> or any element.
 */
:root {
  --acme-color-brand-primary: #007c2b;
  --acme-color-text-default: #14231b;
  --acme-color-surface: #f8f6f0;
  --acme-space-md: 16px;
  --acme-radius-md: 8px;
}

[data-color-scheme="dark"] {
  --acme-color-brand-primary: #4fb8b2;
  --acme-color-text-default: #ecf3ee;
  --acme-color-surface: #120d22;
}

02 · Model Context Protocol

AI agents that propose, people who decide

Connect Claude or any MCP client to https://www.stoaken.com/mcp. Clients with sign-in discovery connect with your Stoaken account; others use an API key. The agent acts as you, with your role on each Brand.

Setting up an assistant or agent? Stoaken for AI assistants has the recipes, and AI tools can read it as /llms.txt.

Reads 16 tools

  • get_startedWhere to begin: your Brands, your role on each, and what you can do there.
  • list_brandsThe Brands you can see, with your role on each.
  • get_brandA Brand's themes, token sets and modes: every id the other tools take.
  • get_token_setOne token set as stored, with the hash to edit it safely.
  • get_theme_tokensA theme's tokens as stored.
  • get_resolved_theme_tokensTokens as a release would publish them, for any mode.
  • list_deprecated_tokensWhat is deprecated, its replacement, and what still uses it.
  • list_releasesA theme's releases, their status and what changed, counted by kind.
  • summarize_releaseA release in plain words: what changes, what breaks, what it reaches.
  • release_changesEvery change in a release, mode by mode, against the one before or any other.
  • release_timelineWhat happened to a release and when: sent, handed on, approved, rejected.
  • export_tokensA live release as CSS, SCSS, Tailwind, Swift, Android or JSON, ready to commit.
  • list_webhooksA Brand's webhooks, their health and latest deliveries.
  • list_membersYour workspaces, or one workspace's members and open invitations.
  • scan_icon_usageRead source files (never run) and list the icons they use, set by set, with exact names (imports, Iconify ids, class names, Material ligatures, SVG files, sprites).
  • find_tailwind_defaultsList the Tailwind defaults a set holds that nobody changed: removable, or still used by another token.

Proposes 21 tools

  • create_webhookAdd a webhook (the secret is returned once).
  • update_webhookChange or re-enable a webhook.
  • rotate_webhook_secretNew signing secret; the old one signs for 24 hours.
  • ping_webhookSend a signed test event.
  • create_workspaceAdd a workspace (say, one per client) next to one you administer.
  • invite_membersInvite up to 50 people with the same access; each gets an email.
  • revoke_invitationWithdraw an open invitation.
  • create_themeCreate a theme from token sets, optionally copying modes.
  • update_themeRename a theme or change its sets.
  • delete_themeDelete a theme that was never released.
  • create_token_setCreate a token set (empty or from DTCG), optionally on top of a theme; lists overrides first; can file a release for review.
  • create_theme_axisAdd an axis (like color-scheme) with its modes to a theme.
  • create_theme_modeAdd a mode to an axis, optionally turning a set on in it.
  • set_mode_bindingSay whether a mode turns a token set on, off, or uses it as a source.
  • add_iconsAdd up to 40 SVG icons to a Brand (cleaned; names with dashes or underscores; skip or replace a taken name). Working copy only.
  • add_icons_by_nameAdd exactly the named icons from public sets (Iconify ids, or names from scan_icon_usage), up to 300 a call, with source, version and licence. The whole set only on an explicit confirm. Working copy only.
  • add_logosAdd up to 5 logo files (SVG, PNG, WebP, JPEG or ICO) to a named logo set, made when missing. Working copy only.
  • propose_asset_releaseSend the Brand's icon and logo changes for review as a release of its main theme; always waits for a person.
  • propose_token_changeEdit a token set and submit it for review.
  • propose_token_editsSet, add, rename or delete tokens (or a whole group) and submit for review.
  • propose_token_deprecationDeprecate a token, reviewed like any other change.

By design, there’s no approve or publish tool. Proposals become releases waiting for review, and write tools have their own rate limit, so a runaway agent can’t flood your reviewers.

03 · Events

Webhooks

Brand Admins add endpoints under Settings → Webhooks. Stoaken sends a small signed event when a release changes state:

  • release.pending_approval
  • release.published
  • release.rejected
  • SignedStandard Webhooks headers: any of its libraries verifies them.
  • RetriedFailed deliveries retry with growing gaps for about a day.
  • LeanIds, status, change counts, a breaking flag. Fetch details with your key.

The Webhook lab sends a real signed sample to your endpoint, checks signatures your receiver got, and has recipes for GitHub Actions, Vercel and Netlify deploys, Slack, Node, Python and no-code tools.

POST /stoaken HTTP/1.1
webhook-id: msg_2Kd9xk3
webhook-timestamp: 1761400000
webhook-signature: v1,K3x0nQ2…
content-type: application/json

{
  "type": "release.published",
  "data": {
    "release_id": "rel_8f2c",
    "version": "1.4.1",
    "changes": { "changed": 3, "added": 1 },
    "breaking": false
  }
}

04 · Terminal

One command to wire up a project

It signs you in, lets you pick a Brand, and sets up the project you run it in for MCP and API access. Then export whenever you like.

New in CLI 0.7: stoaken components push sends your components to a Brand’s Review, worked out on your machine. Stoaken never reads your repository. Components

npx stoaken init
# ✓ Signed in · Brand: Acme · theme: Default
stoaken export --format css --out tokens.css
# ✓ Wrote tokens.css (2 modes)