Getting StartedDeveloper & Embed Guide
Helix Agent
Helix AdvisorHelix OperatorArchitecture & Technical GuideHelix ArchitectureHelix PhasesHelix SandboxHelix MCPHelix Security
MCP Providers
Security & Governance
Billing & Quotas
REST, Gateway & MCP API Reference
API Reference (Redoc)

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-briefing Aggregates recent mission outcomes, pending approvals, and enabled schedules into a spoken standup script.
    • Response: { briefing: { script, estimatedDurationSeconds, whatHappened, whatNeedsYou, whatsScheduled } }
  • 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.

Out-of-Office Delegation & Return Briefing

  • GET /api/v2/out-of-office Returns { 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 }

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 }

Principled Disagreement ("Stop & Push Back") & Shadow Predictor

  • GET /api/v2/disagreements Lists 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 } (persists concernCard when high-risk/pushback triggered)
    • Resolve concern card: { "action": "resolve", "cardId": "<uuid>", "choice": "proceed_as_asked" | "use_suggestion" } → { card }

Teach-by-Showing Playbooks & Memory Consolidation

  • GET /api/v2/playbooks Returns { 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 scrubSecrets and records maskedFieldsCount. Returns 201 { playbook }.
  • 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-hires Returns { consent: { inbox, calendar, chat, files }, suggestions }. Only analyzes sources where explicit consent is true.
  • 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 }.

Mobile Biometric Approvals & WhatsApp Channel Compliance

  • GET /api/v2/mobile-approvals Returns { 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) and phoneNumberId before enabling.
    • Preview inbound normalization: { "action": "inbound_preview", "rawMessage": { ... } }

Reports, Deliverables, Overnight Replay & Performance

  • GET /api/v2/reports?thread=<optionalThreadId> Returns mission checkpoints, durable Postgres-backed artifact summaries, overnightReplay, colleague performance metrics, and contractSummary.
  • POST /api/v2/runs/[id]/undo & POST /api/ledger Triggers workspace rewind on reversible operations ({ ledgerEntryId, action: "rewind" }).

3. Core Workspace, Threads, Agents & Billing APIs

EndpointMethodsPurpose
/api/v2/threadsGETLists workspace-scoped conversation threads (?workspace=<id>).
/api/v2/threads/[id]GET, PATCH, DELETEReads, updates, or removes a specific conversation thread.
/api/v2/runsGET, POSTStarts a new Helix run on a thread or lists active/recent runs.
/api/v2/runs/streamGETServer-Sent Events (SSE) stream of live run progress, steps, and tool calls.
/api/v2/runs/pause, /api/v2/runs/steerPOSTPauses or steers an in-flight run.
/api/v2/approvals, /api/v2/approvals/[id]GET, POSTLists and decides plan/tool approval gates.
/api/v2/missions, /api/v2/missions/[id]GET, PATCHQueries or updates mission state and acceptance criteria.
/api/v2/agents, /api/v2/agents/[id]GET, POST, PATCHManages crew roster, custom specialists, and status.
/api/v2/desktop, /api/v2/desktop/touchGET, POSTProvisions sandbox browser/desktop preview stream (watch_url) and pointer events.
/api/v2/files, /api/v2/files/uploadGET, POSTManages workspace files and deliverable downloads.
/api/v2/settings, /api/v2/connections, /api/v2/billingGET, POST, PUTPersonal/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-Signature HMAC + 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.
Edit this page on GitHub↗