Developers

Agents you can call from code.

Start runs from your backend, stream their steps, answer approvals in your own UI, and get signed webhooks when anything changes. Or hand the whole thing to Claude and Cursor through the MCP server.

Get an API key API changelog

npm install @capstan/sdk

Quickstart

01
Create a key
In Settings → API keys, create a key for one workspace. Give it only the scopes it needs: runs:write to start runs, approvals:write to answer approvals.
.env
CAPSTAN_KEY=cap_live_••••••••••••••••

Start a run

Runs are asynchronous. You get the run back at once, then follow its steps as they happen.

start-run.ts

import { Capstan } from "@capstan/sdk";

const capstan = new Capstan(process.env.CAPSTAN_KEY);

const run = await capstan.agents.run("churn-digest", {
  input: { week: "2026-W44" },
});
console.log(run.id, run.status); // run_9f2c… "running"

Follow it, and answer approvals

Stream steps from the run. When it waits for a person, approve or reject from your own UI, or let Slack do it.

follow-run.ts

for await (const step of run.steps()) {
  console.log(step.status, step.text);

  if (step.status === "waiting") {
    await capstan.approvals.decide(step.approvalId, {
      decision: "approve",
      note: "Looks right",
    });
  }
}

The API

REST with JSON, versioned in the path. Base URL https://api.capstan.dev. Errors come back with a type, a message and the field at fault.

Endpoints
Method	Path	What it does
GET	/v1/agents	List the workspace's agents
POST	/v1/agents/{id}/runs	Start a run with an input
GET	/v1/runs/{id}	Get a run and its status
GET	/v1/runs/{id}/steps	Stream a run's steps (server-sent events)
POST	/v1/approvals/{id}/decision	Approve or reject a waiting step
POST	/v1/replays	Replay an agent on past cases
GET	/v1/usage	Runs and spend this period

Webhooks

Signed with HMAC-SHA256 and retried with backoff. Subscribe to what you need.

run.startedA run begins
run.waitingA step waits for a person
run.completedA run finishes
run.failedA run stops after its retry
budget.reachedAn agent hits its weekly limit

POST https://your-app.com/webhooks/capstan

{
  "type": "run.waiting",
  "created": "2026-11-03T09:00:15Z",
  "data": {
    "run_id": "run_9f2c41",
    "agent": "churn-digest",
    "step": 4,
    "approval_id": "apr_51d0",
    "action": "slack.chat.post",
    "draft": "31 accounts churned last week ($18.4k MRR)…"
  }
}

MCP

Let your AI tools run agents.

Add the Capstan MCP server to Claude, Cursor or any MCP client. They can list your agents, start runs and read traces, with the same scopes and approvals as the key.

list_agents: See the agents this key can run
run_agent: Start a run and wait for the result
get_run: Read a run's trace
decide_approval: Approve or reject, if the key allows it

mcp.json

{
  "mcpServers": {
    "capstan": {
      "url": "https://mcp.capstan.dev",
      "headers": { "Authorization": "Bearer $CAPSTAN_KEY" }
    }
  }
}

SDKs and limits

TypeScriptv2.4.1
@capstan/sdk
Node 20+, Bun, Deno, edge runtimes
Pythonv1.0.3
capstan
Python 3.10+, sync and async clients
CLIv0.9.0
capstan
npx capstan · run, follow, replay
Gov0.6.2
capstan-go
Community, Go 1.22+

Requests: 600 / minute per key
Concurrent runs: 50 on Team · 250 on Business
Step stream: kept 24 h after a run ends
Webhook retries: 8 over 24 h, signed with HMAC-SHA256