Helix — HTTP & Webhook API Reference
All workspace APIs under /api/v2/* authenticate the caller via Supabase SSR cookies (validated by authedOrg() in src/app/api/v2/_lib.ts) and scope every read/write to orgId (team_id). Errors follow the structured envelope from shared/errors.ts.
1. System & Health
GET /api/health
Public readiness probe used by load balancers and smoke checks. Checks Supabase GoTrue /auth/v1/health (gated with 503 if unreachable) and optional engine status (informational).
- Response
200:{ "status": "ok", "checks": { "supabase": "ok", "engine": "ok" }, "time": "2026-11-17T21:30:00.000Z" }
GET /api/auth/me
Returns the authenticated Supabase user profile and active session check (401 if unauthenticated).
2. Colleague Collaboration APIs (/api/v2/*)
Morning Standup & Talk-Back Voice Commands
GET /api/v2/morning-briefingAggregates recent mission outcomes, pending approvals, and enabled schedules into a spoken standup script.- Response:
{ briefing: { script, estimatedDurationSeconds, whatHappened, whatNeedsYou, whatsScheduled } }
- Response:
POST /api/v2/morning-briefing- Body:
{ "transcript": "approve the first one and delay the second" } - Parses numbered talk-back instructions (
approve,reject,delay) against pending approvals and applies authorized state transitions.
- Body:
Out-of-Office Delegation & Return Briefing
GET /api/v2/out-of-officeReturns{ windows, active, latestBriefing }.POST /api/v2/out-of-office- Schedule window:
{ "startsAt": ISOString, "endsAt": ISOString, "autoCoverWithinContracts": true }→201 { window } - Complete window & compile Return Briefing:
{ "action": "complete", "windowId": "<uuid>" }→200 { window }
- Schedule window:
Open Door & Shoulder-Tap Live Supervision
GET /api/v2/desk?thread=<threadId>Returns the current colleague desk supervision state (colleague|shoulder_tap_paused|human_takeover), cursor activity label, and checkpoint metadata.POST /api/v2/desk- Body:
{ "threadId": "<id>", "action": "tap_shoulder" | "take_over" | "hand_back", "checkpoint"?: { ... } } - Response:
{ desk }
- Body:
Principled Disagreement ("Stop & Push Back") & Shadow Predictor
GET /api/v2/disagreementsLists unresolved concern cards, resolved history, and shadow-predicted human verdicts (shadowByApprovalId) for pending approvals.POST /api/v2/disagreements- Evaluate step risk:
{ "action": "evaluate", "assignmentId": "<id>", "goal": "...", "summary": "...", "reversibility": "R0" | "R1" | "R2" | "R3", "actionClass": "..." }→{ shadow, concernRaised }(persistsconcernCardwhen high-risk/pushback triggered) - Resolve concern card:
{ "action": "resolve", "cardId": "<uuid>", "choice": "proceed_as_asked" | "use_suggestion" }→{ card }
- Evaluate step risk:
Teach-by-Showing Playbooks & Memory Consolidation
GET /api/v2/playbooksReturns{ playbooks, patterns, consolidation, conflicts }combining saved UI playbooks, recurring goal pattern detection, and stale memory conflict summary.POST /api/v2/playbooks- Body:
{ "title": "Weekly Invoice Export", "steps": [ { "seq": 1, "surface": "browser", "action": "navigate", "targetSelector": "#export", "narration": "Open export view" } ], "parameters": ["month"], "successCheck": "CSV row count matches invoice ledger" } - Automatically scrubs embedded secrets/tokens via
scrubSecretsand recordsmaskedFieldsCount. Returns201 { playbook }.
- Body:
DELETE /api/v2/playbooks?id=<playbookId>Deletes a saved playbook in the caller's org.
Evidence-Backed Suggested Hires & Explicit Source Consent
GET /api/v2/suggested-hiresReturns{ consent: { inbox, calendar, chat, files }, suggestions }. Only analyzes sources where explicit consent istrue.POST /api/v2/suggested-hires- Body:
{ "consent"?: { "inbox"?: boolean, "calendar"?: boolean, "chat"?: boolean, "files"?: boolean }, "dismissRolePackId"?: string } - Updates per-user source consent or dismisses a role suggestion and recomputes
{ consent, suggestions }.
- Body:
Mobile Biometric Approvals & WhatsApp Channel Compliance
GET /api/v2/mobile-approvalsReturns{ items, whatsapp, parityScreens }, marking biometric requirements for irreversible/external actions.POST /api/v2/mobile-approvals- Decide item:
{ "action": "decide", "itemId": "<id>", "decision": "approved" | "rejected" | "edited", "biometricVerified": true, "reversibility": "R0" | "R1" | "R2" | "R3" } - Configure WhatsApp:
{ "action": "whatsapp_config", "enabled": true, "metaAiTermsVerified": true, "phoneNumberId": "<id>" }Enforces Meta Business Platform AI terms verification (metaAiTermsVerified) andphoneNumberIdbefore enabling. - Preview inbound normalization:
{ "action": "inbound_preview", "rawMessage": { ... } }
- Decide item:
Reports, Deliverables, Overnight Replay & Performance
GET /api/v2/reports?thread=<optionalThreadId>Returns mission checkpoints, durable Postgres-backed artifact summaries,overnightReplay, colleagueperformancemetrics, andcontractSummary.POST /api/v2/runs/[id]/undo&POST /api/ledgerTriggers workspace rewind on reversible operations ({ ledgerEntryId, action: "rewind" }).
3. Core Workspace, Threads, Agents & Billing APIs
| Endpoint | Methods | Purpose |
|---|---|---|
/api/v2/threads | GET | Lists workspace-scoped conversation threads (?workspace=<id>). |
/api/v2/threads/[id] | GET, PATCH, DELETE | Reads, updates, or removes a specific conversation thread. |
/api/v2/runs | GET, POST | Starts a new Helix run on a thread or lists active/recent runs. |
/api/v2/runs/stream | GET | Server-Sent Events (SSE) stream of live run progress, steps, and tool calls. |
/api/v2/runs/pause, /api/v2/runs/steer | POST | Pauses or steers an in-flight run. |
/api/v2/approvals, /api/v2/approvals/[id] | GET, POST | Lists and decides plan/tool approval gates. |
/api/v2/missions, /api/v2/missions/[id] | GET, PATCH | Queries or updates mission state and acceptance criteria. |
/api/v2/agents, /api/v2/agents/[id] | GET, POST, PATCH | Manages crew roster, custom specialists, and status. |
/api/v2/desktop, /api/v2/desktop/touch | GET, POST | Provisions sandbox browser/desktop preview stream (watch_url) and pointer events. |
/api/v2/files, /api/v2/files/upload | GET, POST | Manages workspace files and deliverable downloads. |
/api/v2/settings, /api/v2/connections, /api/v2/billing | GET, POST, PUT | Personal/workspace preferences, integrations/API keys, and billing usage. |
4. Staff Platform, MCP & Public v1 APIs
GET /api/v1/openapi.json— OpenAPI schema for public endpoints (/api/v1/chat/completions,/api/v1/models,/api/v1/status,/api/v1/teams,/api/v1/tokens,/api/v1/usage).GET / POST /api/staff— Authenticated staff colleagues API.POST /api/mcp/staff— JSON-RPC MCP endpoint exposing colleague/staff actions cleanly.POST /api/bridge— Private network bridge registration and session management.
5. Webhooks & External Integrations
POST /api/webhooks/platform— Register and manage outbound workspace event subscriptions (signed with HMAC-SHA256).GET /api/webhooks/platform— List active workspace webhook subscriptions and replay failed deliveries.POST /api/webhooks/email/[secret]— Per-inbox inbound email-to-task routing (X-Helix-SignatureHMAC + allowed-sender validation).POST /api/webhooks/slack/[secret]— Slack Events/Interactive callback handler.POST /api/webhooks/paystack— Billing & subscription settlement events.GET /.well-known/helix-ledger-keys.json— Rotating Ed25519 public keys for offline verification of signed receipt chains.