REST API Overview

The clanker REST API provides programmatic access to skills, artifacts, executions, and billing.

Base URL

https://next.clanker.engineer/api

Authentication

All API requests require authentication via one of:

See Authentication for details, including the External Agents device-code flow for pairing external CLIs.

Request Format

• Content-Type: application/json for POST/PUT/PATCH requests
• Accept: application/json for all requests

curl https://next.clanker.engineer/api/v1/marketplace/skills \
  -H "x-auth-token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Response Format

Success Response

{
  "items": [ ... ],
  "total": 42,
  "limit": 20,
  "offset": 0,
  "hasMore": true
}

Or for simple responses:

{
  "success": true,
  "message": "..."
}

Error Response

Every error is the same envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill not found",
    "details": { "field": "slug", "rule": "required" }
  }
}

Two shapes are deliberately different and worth knowing about:

• Some responses carry an extra top-level sibling next to error when a client needs to branch on it — e.g. isRunning on a skill-install conflict. It is not inside details because that is exactly the field the client reads.

Common Endpoints

Skills (Public)

Skills (User)

Note: Direct skill execution is for interactive use (dashboard, MCP/IDE). For bots, CI/CD, and all external integrations, use Workflows — they provide durable execution, automatic queueing, and crash recovery.

Artifacts

Uploads

The body takes sizeBytes (required: the exact size of the file in bytes, at most 25 MB) and an optional contentType. The file is sent with a PUT to the returned upload.url using the returned upload.headers, and the body must be exactly sizeBytes long — storage refuses any other length. The URL is valid for 300 seconds; finish with POST /api/v1/install using the returned upload.key.

Minting is rate-limited per workspace, by number of URLs per hour and by bytes per day, with smaller allowances for an account without a card on file. Over quota is 429 RATE_LIMITED with a Retry-After header; a missing, zero or oversize sizeBytes is 400 VALIDATION_FAILED; and 503 SERVICE_UNAVAILABLE means uploads are temporarily unavailable, so retry shortly.

Executions

User Profile & API Keys

A pod key is a narrowly scoped key for a development pod’s coding agents. An OAuth app holding the apikey:pod scope can mint one for its consenting user, and the key can revoke itself; see Agent Permissions.

Device Activation (External Agents)

For agents that need a fresh API key paired through the mobile app’s device-flow (8-char XXXX-XXXX user code). RFC 8628 device authorization — the API key is workspace-bound at issuance.

Agent Permissions (scoped consent)

For agents that already hold an API key and want to declare the scope set they actually need — the user approves a scoped consent in the mobile app, and a per-request grant token is issued. Full details in /skill.md § “Agent Permissions”.

Grant tokens are sent via x-permission-grant: <token> on subsequent calls. Permission failures use the standard envelope — a credential missing a scope gets 403 with error.code = FORBIDDEN and a message naming the scope. Branch on the code, never on the message.

Billing

Workflows

Workspaces

Connectors

GitHub-specific (first-class)

Agents

Threads (Chat History)

Threads are conversation containers — chat messages live inside them.

Workspace Memory

Working memory is a workspace-scoped Markdown document the agent reads and writes between turns.

Secrets

Per-workspace encrypted credentials. Skills request them at execution time; the screen never shows the raw value.

Channels

The inbound webhook (/api/webhooks/whatsapp/{agentId}, GET for Meta’s verification challenge and POST for message events) is not listed above: it is called by Meta, not by an API client, and authenticates with an HMAC-SHA256 signature rather than a Clanker credential. Inbound third-party callbacks live under /api/webhooks/* and are deliberately unversioned — their URLs sit in someone else’s console, so a version bump would be a coordinated external edit.

Search

Activity — what CHANGED

The workspace change log. See Activity Endpoints.

Traces — what agents DID

Agent runs, turn by turn. See Traces Endpoints.

Workspace Dashboard

These are scoped by the x-workspace-id header (or the workspace baked into an API key) — there is no workspace id in the path. See Workspace scoping.

Account Settings

Personal, account-level state — distinct from the workspace settings above. A transcript is shared, so the language the agent replies in is a workspace property; the language your UI renders in is yours.

Audit Logs

Bootstrap / Identity

Real-time Events

MCP

MCP traffic is served by the dedicated MCP edge worker, not by the REST backend. Point clients at https://next.clanker.engineer/mcp/ and the request is routed transparently.

Rate Limiting

API requests are rate-limited to 100 requests per minute per user. Skill execution endpoints are limited to 30 requests per minute. See Rate Limits for the rest, including how callers are identified.

Rate limit headers are included in responses:

x-ratelimit-limit: 100
x-ratelimit-remaining: 98
x-ratelimit-reset: 45

Pagination

List endpoints support pagination:

GET /api/v1/artifacts?limit=20&offset=0

SSE Streaming

Execution results stream over Server-Sent Events (SSE) using the Sessions API three-step flow:

1. Create an idle execution — POST /api/v1/executions
2. Connect to the live stream — GET /api/v1/executions/:id/stream-token returns a signed sseUrl; open it before step 3
3. Send input to trigger the run — POST /api/v1/executions/:id/events with a user.message event

The stream replays all history from the beginning, then delivers live events, and closes automatically when session.status_idle arrives.

See Executions API for event types, stop reasons, reconnect parameters, and the session-level stream.

Workflow Results

Launching a workflow (POST /api/v1/workflows/:id/launch) accepts only inputs and returns a runId immediately. The run is asynchronous — retrieve its outcome by polling the run or streaming it:

# Poll until terminal
curl https://next.clanker.engineer/api/v1/workflows/runs/run-1770000000000-8fq2k1 \
  -H "x-api-key: ck_live_xxxxxxxxxxxxx"
# → { "run": { "status": "success", ... }, "steps": { "<stepId>": { ... } } }

Terminal statuses are success, failed and canceled; suspended means the run is parked waiting for a human and resumes on request.

For live step events, open the SSE stream at GET /api/v1/workflows/runs/:runId/events (using the runId from launch). Workflows started from a chat thread also report completion back into that thread automatically.

See the Workflows API for full details.

Error Codes

These are the values of error.code. Codes are stable; the accompanying error.message is not.

This table is pinned against the server’s own ErrorCodes by server/__tests__/api-docs-drift.test.ts — adding a code without a row here, or leaving a row for a code that no longer exists, fails that test.

Statuses are the usual mapping, not a guarantee: a route may answer with a more specific status when it has one. Branch on the code and read the status as a hint, not the reverse.

SDK & Libraries

Currently, no official SDKs are available. We recommend using the MCP protocol with compatible AI clients, or making direct HTTP requests.

Example with fetch:

const response = await fetch("https://next.clanker.engineer/api/v1/marketplace/skills", {
  headers: {
    "x-auth-token": process.env.CLANKER_AUTH_TOKEN,
    "Content-Type": "application/json",
  },
});

const skills = await response.json();

Example with curl:

curl https://next.clanker.engineer/api/v1/marketplace/skills \
  -H "x-auth-token: $CLANKER_AUTH_TOKEN"