API Reference

Hyphen is API-first. Every capability — workflow creation, execution, agent orchestration, approvals, OAuth configuration — is an HTTP endpoint.

Base URL

text

http://localhost:3009

Replace with your deployed instance URL in production.

Authentication

All requests require the X-Org-Id header for multi-tenant isolation:

bash

curl -H "X-Org-Id: your-org-id" http://localhost:3009/workflows

Every workflow, run, action, table, and credential is scoped to the organization specified in this header.

OpenAPI Specification

The full interactive API spec is available here:

Hyphen API (OpenAPI 3.0) — Every endpoint, request/response schema, and parameter documented

Endpoints at a Glance

Health & Discovery

GET/health

Verify the API is running.

GET/builtin-actions

List pre-registered OAuth business tools (Gmail, Slack, Outlook).

Organization Configuration

POST/org-config

Store or update an encrypted configuration key (API keys, connection strings, secrets).

GET/org-config

List all configuration keys (values masked).

Actions

POST/actions

GET/actions

List all registered actions.

GET/actions/:id

Get action details.

PUT/actions/:id

Update an action.

Workflows

POST/workflows

Create a workflow definition.

GET/workflows

List all workflows.

GET/workflows/:id

Get workflow details.

PUT/workflows/:id

Update a workflow.

DELETE/workflows/:id

Delete a workflow.

Execution

POST/workflows/:id/execute

Execute a workflow with an input payload. Returns a run ID.

GET/runs/:runId/status

Get current run status, context, and step outputs.

Approvals

POST/approvals/:runId/:stepIndex

Submit an approval decision for a paused workflow.

GET/approvals/:runId

List pending approvals for a run.

Standalone Agents

:::api POST /agents/execute Execute an AI agent outside of a workflow. Supports sync and async modes (?async=true). :::

:::api GET /agents/:id/status Get agent status. Add ?include_trace=true for reasoning trace. :::

GET/agents/:id/trace

Get the full reasoning trace (audit trail) — every thought, action, and observation.

POST/agents/:id/resume

Resume a paused agent with human input.

DELETE/agents/:id

Cancel a running agent.

:::api GET /agents List agent runs. Filter by ?status=paused, ?status=running, etc. :::

Custom Tables

POST/custom-tables

Create a new table with typed fields.

POST/custom-tables/:name/insert

Insert a record.

POST/custom-tables/:name/bulk-insert

Insert multiple records.

PUT/custom-tables/:name/update

Update records matching criteria.

GET/custom-tables/:name

View all data in a table.

GET/custom-tables/:name/audit

View the audit log for a table.

External Forms

POST/external-forms

Create an external-facing form for data collection.

POST/external-forms/:id/submit

Submit a form response.

GET/external-forms/:id/submissions

Get all submissions.

AI Workflow Generation

POST/ai/generate-workflow

Generate a workflow from a natural language description.

GET/ai/generate-workflow/:id/status

Check generation status.

GET/ai/generate-workflow/:id

Retrieve the generated workflow spec.

POST/workflows/create-from-ai

Create a workflow from AI-generated output (registers actions and tables too).

OAuth Business Tools

GET/oauth/providers

List available OAuth providers and configuration status.

POST/oauth/:provider/app-credentials

Store OAuth app credentials (client_id, client_secret).

GET/oauth/:provider/authorize

Get authorization URL for user consent flow.

GET/oauth/connections

List all OAuth connections for the organization.

Error Responses

All endpoints return standard HTTP status codes:

Status	Meaning
`200`	Success
`201`	Created
`400`	Bad request — invalid parameters or workflow definition
`404`	Not found — workflow, run, or action doesn't exist
`409`	Conflict — duplicate action name or table name
`500`	Server error

Error responses include a message field:

json

{ "error": "Workflow not found", "message": "No workflow with id 'wf_xyz' for org 'your-org'" }

Rate Limiting

Rate limits are applied per organization. Monitor usage via the admin metrics endpoint.

For AI agents: Fetch /llms.txt for the complete documentation in structured text optimized for LLM consumption.