--- title: "API Reference" canonical: "https://pilot.docs.mindburn.org/reference" source: "pilot/docs/api.md" edit: "https://github.com/Mindburn-Labs/pilot/edit/main/docs/api.md" section: "reference" access: "public" sensitivity: "public" last_reviewed: "unknown" checksum_sha256: "sha256:497af58abaf099a649e866ff226f4b01d84391764cdb064158d954b094f2b052" build_timestamp: "2026-05-24T13:42:52.320Z" --- # Pilot API Reference Base URL: `http://localhost:3100` (or your deployed gateway URL) ## Audience Use this page if you are writing a client, testing a self-hosted deployment, wiring a connector, or auditing API behavior. It is a public reference hub for routes, auth, workspace context, payload shapes, job surfaces, receipts, and diagnostics. ## Outcome After this page you should be able to: - authenticate with email, Telegram, or API keys; - pass workspace context correctly; - use the public-safe auth, workspace, task, capability, and audit endpoints; - understand where HELM governance receipts appear; - collect useful diagnostics when an API call fails. ## API Surface Map ```mermaid flowchart TD subgraph Ingestion["1. Ingestion & Context Plane"] Client["Client"] Auth["Auth"] Workspace["Workspace context"] Tasks["Tasks and operators"] Knowledge["Knowledge and applications"] Connectors["Connectors"] Launch["Launch"] Incidents["Incidents"] end subgraph Evaluation["2. Evaluation & Policy Plane"] Audit["Audit and approvals"] end subgraph Ledger["4. Tamper-Evident Ledger Plane"] Governance["Governance receipts"] end %% Operational Flow Edges Client --> Auth Auth --> Workspace Workspace --> Tasks Workspace --> Knowledge Workspace --> Connectors Workspace --> Launch Workspace --> Incidents Workspace --> Audit Tasks --> Governance Connectors --> Governance Launch --> Governance %% Premium Styling Rules style Audit fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff style Governance fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff ``` ## Source Truth Route behavior is backed by `services/gateway/src/routes/`, Zod payloads and shared types in `packages/shared/`, database domains in `packages/db/src/schema/`, and HELM receipt wiring in `packages/helm-client/`. If a route description differs from code or tests, update this file. ## Authentication All protected endpoints require one of: - **Bearer token:** `Authorization: Bearer ` - **API key:** `X-API-Key: hp_` - **Workspace context:** authenticated non-auth routes should also include `X-Workspace-Id: ` when the workspace is not already encoded in the path. Session tokens are obtained via `/api/auth/email/request` + `/api/auth/email/verify` or `/api/auth/telegram`. Session tokens rotate automatically after 24 hours — check the `X-New-Token` response header. --- ## Auth ### POST /api/auth/email/request Request a magic link code. ```json { "email": "you@example.com" } ``` Response: `{ "sent": true, "email": "...", "code": "123456" }` (code only in dev mode) ### POST /api/auth/email/verify Verify magic link code and get a session. ```json { "email": "you@example.com", "code": "123456" } ``` Response: `{ "token": "...", "user": { "id", "name", "email" }, "workspace": { "id", "name" } }` ### POST /api/auth/telegram Authenticate via Telegram Web App initData. ```json { "initData": "" } ``` ### POST /api/auth/apikey Create an API key (requires auth). ```json { "name": "my-key" } ``` Response: `{ "key": "hp_...", "name": "...", "expiresAt": "..." }` ### DELETE /api/auth/session Logout / invalidate current session. ### POST /api/auth/invite/:token Accept a workspace invite. ```json { "email": "you@example.com" } ``` --- ## Workspace ### GET /api/workspace/:id Get workspace details with members. ### GET /api/workspace/:id/settings Get workspace settings (policy, budget, model config). ### PUT /api/workspace/:id/settings Update workspace settings. ```json { "policyConfig": { "maxIterationBudget": 50, "blockedTools": [] }, "budgetConfig": { "monthlyLlmBudget": 100, "currency": "USD" }, "modelConfig": { "provider": "openrouter", "model": "anthropic/claude-sonnet-4-20250514", "temperature": 0.7 } } ``` ### PUT /api/workspace/:id/mode Switch workspace mode. ```json { "mode": "discover" } ``` Valid modes: `discover`, `decide`, `build`, `launch`, `apply` ### POST /api/workspace/:id/invite Generate invite link. ```json { "role": "member", "email": "partner@example.com" } ``` Response: `{ "inviteUrl": "...", "inviteToken": "...", "role": "member", "expiresIn": "7 days" }` --- ## Tasks ### GET /api/tasks List tasks for the workspace. Query: `?workspaceId=...` or pass `X-Workspace-Id`. ### POST /api/tasks Create a task and write audit/evidence metadata. ```json { "title": "Draft launch checklist", "description": "Use existing workspace evidence.", "workspaceId": "..." } ``` ### PUT /api/tasks/:id/status Update a task status. ```json { "status": "queued" } ``` ### POST /api/tasks/:id/run Run a governed task through the orchestrator. ### GET /api/tasks/:id/runs List task run history for the workspace-scoped task. ## Audit ### GET /api/audit List audit log entries. Query: `?workspaceId=...&limit=50`. ### GET /api/audit/approvals List approvals. Query: `?workspaceId=...&status=pending`. ### PUT /api/audit/approvals/:id Resolve an approval. ```json { "status": "approved" } ``` ### GET /api/audit/violations List policy violations for the workspace. ## Capabilities ### GET /api/capabilities Return the public capability registry and readiness summary. ### GET /api/capabilities/:key Return one capability state, blocker list, owner, and required eval gate. ## Protected Route Families Pilot also has protected operator, connector, launch, YC, governance, compliance, command, browser, eval, lifecycle, secret, managed Telegram, and tenant administration route families. Anonymous docs intentionally do not expose those route paths. Authenticated customer or staff docs connect those surfaces when the viewer has access, and secret-bearing payloads remain excluded from sitemap, search, Markdown, LLM, and MCP exports. ## Receipts And Governance When HELM is configured, governed LLM calls and consequential tool actions should attach decision metadata to task runs and evidence rows. Use: - `GET /api/governance/status` - `GET /api/governance/receipts` - `GET /api/governance/receipts/:decisionId` - `GET /api/audit?workspaceId=...` ## Error Codes And Diagnostics For a failed API call, collect method, path, workspace ID, request ID, response status, sanitized payload shape, auth mechanism, task ID if relevant, and HELM decision ID when present. Do not include secrets, raw connector tokens, or private session snapshots. ## Troubleshooting | Symptom | Likely Cause | Fix | | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------ | | request returns 401 | missing bearer token, API key, or expired session | authenticate again and check `X-New-Token` | | route returns 404 for workspace data | workspace context is missing or wrong | pass `X-Workspace-Id` or use workspace-scoped path | | connector action fails | grant is missing, expired, or not validated | inspect connector grant status and revalidate | | task creates but never runs | pg-boss or orchestrator is unavailable | check `/health` and job queue status | | governed action has no receipt | HELM is not configured or route is not governed | check `HELM_GOVERNANCE_URL`, startup logs, and audit entries |