~10 min read

API Reference -- v1

StateAnchor exposes a versioned REST API under /api/v1 for programmatic integrations. All endpoints return JSON. Errors follow the shape { error: string }.

Base URL

https://stateanchor.dev

Authentication

Two auth methods are accepted on v1 endpoints:

API keys are scoped to one of three permission levels: read, write, or sync. Endpoints that mutate state require at least write scope.

Billing

Creates a Stripe checkout session for a subscription plan. Requires a Clerk session.

// Request body
{ "priceKey": "gate_only_pro" | "gate_only_team" | "pipeline_pro" | "pipeline_team" | "enterprise" }

// Response 200
{ "url": "https://checkout.stripe.com/..." }
// → redirect to this URL to complete checkout

Creates a Stripe billing portal session to manage subscription, update payment method, or cancel. Requires a Clerk session. Returns 404 if no billing account exists (user has never subscribed).

// Response 200
{ "url": "https://billing.stripe.com/..." }
// → redirect to this URL

Returns the authenticated user’s current credit balance and plan tier. Requires a Clerk session.

GET /api/user/credits

// Response
{
  "credits": 3,
  "plan_tier": "free" | "pro" | "team" | "enterprise",
  "stripe_subscription_status": "active" | "canceled" | null
}

API Key Management

API keys can be created and revoked from the Settings → API Keys page, or programmatically via the endpoints below. Requires a Clerk session (not an API key).

Returns all active (non-revoked) keys. The full key value is never returned here -- only the prefix and metadata.

// Response
{
  "keys": [
    {
      "id": "uuid",
      "key_prefix": "wf_live_XXXX",
      "name": "CI pipeline",
      "scopes": ["read", "sync"],
      "last_used_at": "2026-04-01T12:00:00Z",
      "created_at": "2026-03-01T00:00:00Z"
    }
  ]
}

The full key value (wf_live_...) is returned only once at creation. Copy it immediately -- it cannot be retrieved again.

// Request body
{ "name": "My CI pipeline", "scopes": ["read", "sync"] }

// Response 201
{
  "id": "uuid",
  "key": "wf_live_...",        // full value -- store now
  "key_prefix": "wf_live_XXXX",
  "name": "My CI pipeline",
  "scopes": ["read", "sync"],
  "created_at": "2026-04-26T00:00:00Z"
}

Revocation is permanent. The key becomes invalid immediately.

Atomically revokes the specified key and issues a replacement with the same name and scopes. The new full key value is returned once. Rate-limited to 10 rotations per hour per user.

// Request body
{ "keyId": "uuid-of-key-to-rotate" }

// Response 200
{
  "id": "new-uuid",
  "key": "wf_live_...",        // new full value -- store now
  "key_prefix": "wf_live_YYYY",
  "name": "CI pipeline",
  "scopes": ["read", "sync"],
  "created_at": "2026-04-26T01:00:00Z"
}

Projects

Paginated audit log for a project. Query params: from, to (ISO timestamps), lane (ERR | WARN | INFO | PASS), limit (1-100, default 20), cursor (opaque pagination token).

GET /api/v1/projects/proj_123/audit?lane=ERR&limit=10
Authorization: Bearer wf_live_...

// Response
{
  "results": [
    {
      "id": "sync-run-uuid",
      "verdict": "ERR",
      "ref": "refs/heads/main",
      "commit": "abc123",
      "created_at": "2026-04-25T10:00:00Z"
    }
  ],
  "next_cursor": "eyJ...",
  "has_more": true
}

Returns a structured report of which consuming services or SDK methods are affected by the most recent breaking change.

Lists all active drift exceptions for the project. Requires read scope.

Returns the live deployed OpenAPI spec that StateAnchor is tracking for this project.

Generates a SOC 2 CC8.1-mapped evidence package (JSON or Markdown) covering gate decisions, exceptions with owner/reason/expiry, and a Merkle log integrity statement. Body params: from, to (ISO date range), format (json | markdown, default json). Requires read scope. Available on Team tier and above.

// Request body
{ "from": "2026-01-01", "to": "2026-04-27", "format": "markdown" }

// Response 200
{
  "format": "markdown",
  "content": "# StateAnchor SOC 2 CC8.1 Evidence Package\n..."
}

Returns published changelog entries for a project, derived from gate verdicts. Each entry includes a structured lane breakdown and an AI-generated developer_summary. Query params: limit (default 20), cursor (opaque pagination token), status (draft | published).

GET /api/projects/proj_123/changelog?status=published&limit=5
Authorization: Bearer wf_live_...

// Response
{
  "entries": [
    {
      "id": "uuid",
      "version": "2026-04-27T10:00:00Z",
      "lane": "ERR",
      "developer_summary": "Removed the /users/{id} endpoint. Existing callers will receive 404.",
      "err_count": 1,
      "warn_count": 0,
      "info_count": 2,
      "published_at": "2026-04-27T10:05:00Z"
    }
  ],
  "next_cursor": "eyJ...",
  "has_more": false
}

Publishes a draft changelog entry. Requires write scope. Body: { entryId: string }.

Returns aggregate gate stats for the trailing 30 days: total syncs, gate blocks, breaking changes caught, and artifacts generated. Shown in the cockpit stats bar once the project has 5 or more sync runs.

GET /api/projects/proj_123/protection-summary
Authorization: Bearer wf_live_...

// Response
{
  "total_syncs": 42,
  "gate_blocks": 3,
  "breaking_changes_caught": 7,
  "artifacts_generated": 39
}

Returns a zero-LLM getting-started scaffold derived from the project’s current spec: endpoint table, auth overview, and example request stubs. Also accessible at the public docs scaffold page.

GET /api/projects/proj_123/docs-scaffold
Authorization: Bearer wf_live_...

// Response
{
  "scaffold": "# payments-api Getting Started\n..."
}

Services

Lists all services visible to the authenticated caller.

Triggers a new sync run for the service. Requires sync scope. Returns a syncRunId you can poll for results.

Lists generated SDK artifacts for a service.

OpenAPI

Returns the raw OpenAPI specification that StateAnchor is currently tracking for the project. Useful for generating client SDKs or integrating with other tooling.

GitHub Integration

Returns the GitHub App installation status for the authenticated user. Used by the onboarding wizard to gate the Step 1 → Step 2 transition. Requires a Clerk session.

GET /api/github/installation-status

// Response -- installed
{
  "installed": true,
  "installation_id": 12345678,
  "account_login": "acme-org",
  "repo_count": 4
}

// Response -- not installed
{ "installed": false }

Utilities

Adds an email address to the changelog newsletter via Resend. Public endpoint -- no auth required. Rate-limited to 3 requests per hour per IP.

// Request body
{ "email": "user@example.com" }

// Response 200
{ "ok": true }

// Response 409 -- already subscribed
{ "error": "already_subscribed" }

Gate Check (Action endpoint)

The gate-check endpoint is used by the GitHub Action and CI integrations. It uses a short-lived action token (exchanged via GitHub OIDC), not a long-lived API key.

Rate-limited to 100 requests per minute per API key and 60 requests per minute per repo (in-memory layer). Returns a verdict of ERR, WARN, or PASS with structured evidence.

Rate Limiting

Limits marked "in-memory" reset on serverless cold starts. Persistent limits require UPSTASH_REDIS_REST_URL to be configured. Responses that are rate-limited include a Retry-After header (seconds).

Error codes

SDK

There is no official StateAnchor client SDK yet. All requests are plain HTTP. The GitHub Action handles the gate-check flow automatically -- you only need to call the v1 REST API directly for custom integrations.

See the GitHub Action reference for the recommended CI integration pattern.