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

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

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 <session-token>
• API key: X-API-Key: hp_<key>
• Workspace context: authenticated non-auth routes should also include X-Workspace-Id: <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.

{ "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.

{ "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.

{ "initData": "<telegram-web-app-init-data>" }

POST /api/auth/apikey

Create an API key (requires auth).

{ "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.

{ "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.

{
  "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.

{ "mode": "discover" }

Valid modes: discover, decide, build, launch, apply

POST /api/workspace/:id/invite

Generate invite link.

{ "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.

{ "title": "Draft launch checklist", "description": "Use existing workspace evidence.", "workspaceId": "..." }

PUT /api/tasks/:id/status

Update a task status.

{ "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.

{ "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