REST API overview
The full, generated reference for every endpoint is under
REST API. It is produced from the running FastAPI app’s OpenAPI 3.1
document and regenerated by scripts/export_openapi.py. Every endpoint is
available on self-hosted installs with no plan gating.
Base URL
Section titled “Base URL”| Setup | Base |
|---|---|
| Docker Compose | http://localhost:3000 (nginx) |
| Local uvicorn | http://localhost:8000 |
Interactive docs are also served by the API itself at /docs (Swagger UI)
and /redoc.
Authentication
Section titled “Authentication”curl -X POST $BASE/auth/token -d 'username=admin&password=admin'# → {"access_token": "…", "token_type": "bearer", "refresh_token": "…"}Send Authorization: Bearer <access_token>. Refresh with
POST /auth/refresh and {"refresh_token": "…"}; both tokens rotate. Note
that auth routes live at /auth, not /api/auth.
SSE (/api/events) and WebSocket clients cannot set headers and pass the
access token as ?token=; refresh tokens are rejected there too.
Workspace selection
Section titled “Workspace selection”Add X-Workspace-Id: <id> to act in a specific workspace you belong to.
Without it the request uses your active workspace. See
Workspaces and tenancy.
Other token types
Section titled “Other token types”| Token | Prefix | Scope | Minted by |
|---|---|---|---|
| MCP token | ycp_ |
one workspace, capability list | POST /api/mcp/tokens (admin) |
| Ingest token | wbi_ |
one workbook, rows ingest only | POST /api/v2/workbooks/{id}/ingest-token (editor) |
Both are shown once and stored hashed.
Rate limits
Section titled “Rate limits”Limits are keyed by workspace, then bearer-token fingerprint, then IP.
Workbook runs and source runs: 20 per minute. Single-cell runs: 120 per
minute. Several lead endpoints: 20 to 60 per minute. Exceeding a limit returns
429.
Idempotency
Section titled “Idempotency”Ingest accepts an Idempotency-Key header (replayed for 7 days with
Idempotent-Replay: true). Workbook actions, automation actions and MCP writes
accept an idempotency_key field and de-duplicate per workspace.
Errors
Section titled “Errors”Standard FastAPI shapes: {"detail": "…"} for 4xx, validation errors as a
list under detail for 422. Cross-tenant object ids return 404.
Route groups
Section titled “Route groups”| Prefix | Area |
|---|---|
/auth, /api/users |
Login, refresh, users |
/api/workbooks |
Workbooks, columns, rows, cells, runs, estimates, budgets, views, sources, import, ingest |
/api/leads, /api/jobs, /api/events |
Lead store, collection jobs, live events |
/api/copilotkit |
Chat and autopilot |
/api/outreach |
Sequences, SMTP, suppressions, drafts, unsubscribe, bounce webhook |
/api/signals, /api/watches, /api/automations |
Signals, watches, trigger rules |
/api/templates, /api/functions |
Recipe gallery, reusable column chains |
/api/mcp/tokens |
MCP token management |
/api/settings, /api/workspaces, /api/billing, /api/meta |
Keys and integrations, workspace management, billing, metadata |