API Reference

Base URL

text
https://apisvr.tryhyphen.com

Authentication

Hyphen supports three access patterns:

  • Gateway mode: Authorization: Bearer sk-hyp-* (gateway injects tenant context)
  • Direct engine mode: X-Org-Id: <org-id>
  • SDK mode: publishable key pk_live_* (org resolved server-side, scoped access)

Admin routes are available for platform operators.

Core Engine Endpoints

Health

  • GET /health
  • GET /health/ready
  • GET /builtin-actions

Workflows and Runs

  • POST /workflows
  • GET /workflows
  • GET /workflows/:id
  • PUT /workflows/:id
  • DELETE /workflows/:id
  • POST /workflows/:id/execute (body must be { "input": { ... } })
  • GET /runs/:runId/status

Approvals and Forms

  • GET /approvals — List all pending approvals for the org
  • POST /approvals/:runId/:stepId
  • GET /approvals/:runId
  • POST /forms/:runId/:stepId/submit (body: { "data": { ... } })
  • GET /forms/pending

Agents

  • POST /agents/execute — body accepts optional previous_run_id to inject prior run context
  • GET /agents
  • GET /agents/:id/status — response includes previous_run_id when set
  • GET /agents/:id/trace
  • POST /agents/:id/resume
  • DELETE /agents/:id

Actions

  • POST /actions
  • GET /actions
  • GET /actions/:id
  • PUT /actions/:id

Custom Tables

  • POST /custom-tables
  • GET /custom-tables/:name
  • DELETE /custom-tables/:name
  • POST /custom-tables/:name/insert
  • POST /custom-tables/:name/bulk-insert
  • PUT /custom-tables/:name/update
  • GET /custom-tables/:name/rows — List rows (SDK-compatible)
  • POST /custom-tables/:name/rows — Insert a row (SDK-compatible)
  • PATCH /custom-tables/:name/rows/:rowId — Update a row by ID (SDK-compatible)
  • GET /custom-tables/:name/audit

Documents

  • POST /documents
  • POST /documents/from-url
  • POST /documents/bulk-upload
  • GET /documents
  • GET /documents/:id
  • GET /documents/:id/download
  • PATCH /documents/:id
  • POST /documents/:id/versions
  • DELETE /documents/:id
  • GET /documents/:id/audit
  • GET /documents/storage-usage

Webhooks (Registrations)

  • POST /webhooks
  • GET /webhooks
  • GET /webhooks/:id
  • PATCH /webhooks/:id
  • DELETE /webhooks/:id

OAuth

  • GET /oauth/providers
  • POST /oauth/:provider/app-credentials
  • GET /oauth/:provider/app-credentials
  • GET /oauth/:provider/authorize
  • GET /oauth/:provider/callback
  • GET /oauth/connections
  • GET /oauth/connections/:provider/:accountId
  • DELETE /oauth/connections/:provider/:accountId
  • POST /oauth/connections/:provider/:accountId/refresh

AI Generation

  • POST /ai/generate-workflow
  • GET /ai/generate-workflow/:generation_id/status
  • GET /ai/generate-workflow/:generation_id
  • POST /workflows/create-from-ai
  • GET /workflows/create-from-ai/:processId
  • GET /workflows/generation-status/:processId

Org Config and Schema

  • POST /org-config
  • GET /org-config
  • POST /schemas
  • GET /schemas/:id
  • POST /utils/generate-dag

SDK Endpoints

These endpoints are called by the Ops Console SDK using a publishable key (pk_live_*). They provide scoped access to tasks, tables, documents, and authentication for embedded UI components.

Sessions

  • POST /sdk/auth/session — Create anonymous session
  • GET /sdk/config — Get SDK configuration

Tasks

  • GET /sdk/tasks — List pending tasks
  • POST /sdk/tasks/:taskId/decide — Approve or reject a task

Tables

  • GET /sdk/tables/:name/rows — List table rows (paginated)
  • POST /sdk/tables/:name/rows — Insert a row
  • PATCH /sdk/tables/:name/rows/:rowId — Update a row (inline editing)

Documents

  • GET /sdk/documents — List documents
  • POST /sdk/documents — Upload a document

Authentication

  • POST /sdk/auth/otp/request — Send OTP code to registered email
  • POST /sdk/auth/otp/verify — Verify OTP and upgrade session

Agents

  • POST /sdk/agents/execute — Launch an agent (async, returns agent_run_id). Accepts optional previous_run_id for cross-run context
  • GET /sdk/agents — List agent runs
  • GET /sdk/agents/:agentId/status — Get agent status with reasoning trace
  • GET /sdk/agents/:agentId/trace — Get full reasoning trace
  • POST /sdk/agents/:agentId/resume — Resume a paused agent with human input
  • DELETE /sdk/agents/:agentId — Cancel a running agent

Discovery

  • GET /sdk/actions — List registered actions (for tool picker)
  • GET /sdk/workflows — List workflows (for tool picker)

Events

  • GET /sdk/events — Server-sent event stream (real-time updates)

Gateway Endpoints

  • GET /health
  • POST /gateway/signup
  • Tenant (management token): /gateway/account, /gateway/orgs, /gateway/orgs/:orgId/keys, /gateway/orgs/:orgId/usage, /gateway/licenses
  • Licensing: POST /licensing/validate, GET /licensing/public-key

Error Shape

Typical error body:

json
{
  "error": "Validation failed",
  "message": "..."
}