REST API

The REST API is in the free tier, rate-limited, with scoped tokens and a published OpenAPI document. Everything the dashboard does, the API does: it is the same /v1 routes the dashboard calls, authenticated with an fwz_ key instead of a session. There is no second code path.

• The rendered reference — every operation with its request and response schema.
• Error codes — what each code in the envelope means, and what to do about it. Every non-2xx body carries a docsUrl pointing at its own anchor there.
• openapi.json — the document both of the above are built from.

Get a key

1. Sign in and open Settings → API keys. Minting a key needs the owner or admin role.
2. Create key, give it a name, and tick the narrowest scopes that do the job: freeze:read for a deploy gate, freeze:write to freeze and thaw. Scopes are fixed at creation and can never be widened.
3. Pick an expiry. A key declared as an agent key must expire within 90 days.
4. Copy the secret. It is shown once. Then export FWOZEN_TOKEN=fwz_live_… and send it as Authorization: Bearer $FWOZEN_TOKEN.

A key is organisation-wide and never user-scoped, so the scope list is the authorization. Two routes it can never call are minting another key and setting enforcement up: both are session-only and answer 403 credential_type_not_allowed, never a 401, so a script can tell the two apart. Rotating a key issues a new secret and keeps the old one working for a grace window, which is what makes a rotation something you can roll through CI without a deploy.

Calling it

curl -s "https://api.fwozen.com/v1/freeze-state?repo=acme/api-server" \
  -H "Authorization: Bearer $FWOZEN_TOKEN"

• JSON in, JSON out. Send Content-Type: application/json on anything with a body. curl -d declares a form body on its own and the API answers 400 unsupported_content_type.
• Idempotency. Idempotency-Key on a write makes a retry safe. The same key with a different body is a 409, so use one key per intent.
• Pagination. Cursor-based. Follow the cursor the response gives you rather than building one.
• Rate limits. Read RateLimit-Remaining and RateLimit-Reset off every credentialled response and honour Retry-After on a 429. No ceiling is published here, because the numbers are operational settings and a figure in prose would be a promise nobody made.
• Unknown fields. /v1 is additive-only: new response fields ship without notice, so ignore the ones you do not know and treat an unfamiliar enum value as opaque.

Connect an MCP client

The same routes are a streamable-HTTP MCP server at https://api.fwozen.com/mcp. It takes the same two credentials the REST API does, and there is no MCP-specific token to go looking for. The header path is the one that works everywhere:

claude mcp add --transport http fwozen https://api.fwozen.com/mcp \
  --header "Authorization: Bearer $FWOZEN_TOKEN"

Clients that read a config file take the same two lines:

{
  "mcpServers": {
    "fwozen": {
      "type": "http",
      "url": "https://api.fwozen.com/mcp",
      "headers": { "Authorization": "Bearer fwz_live_…" }
    }
  }
}

There is an OAuth path too, for clients that support client id metadata documents: point the client at the same URL with no header and it will be sent to the consent page. Dynamic client registration is deliberately not offered, so a client that can only do DCR has to use the header instead. A request with no credential answers 401 with a WWW-Authenticate header naming /.well-known/oauth-protected-resource, which is the discovery chain an MCP client follows on its own.

The tools are thin adapters over the routes below and carry the same authorization: a key that cannot call a route cannot call its tool. Reads and writes are never mixed in one tool, fwozen_enable_repos takes an explicit repository list, and fwozen_end_freeze is marked destructive and refuses without confirm: true.

Every public route

Generated from the same route table the OpenAPI document and llms-full.txt are generated from. auth says which credential a route takes: key is an fwz_ API key, session is a signed-in session or a device-flow token, both is either, and none takes no credential at all. Where scopes are listed, a key needs any one of them.