REST API Overview

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

Base URL

https://clanker.net/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://clanker.net/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

Executions

User Profile & API Keys

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://clanker.net/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.

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://clanker.net/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://clanker.net/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://clanker.net/api/v1/marketplace/skills \
  -H "x-auth-token: $CLANKER_AUTH_TOKEN"