Hyphen API
Complete REST API for the Hyphen platform — infrastructure for governed autonomous AI. Build workflows, execute AI agents, manage approvals, and orchestrate business operations with full audit trails.
Actions
Register and manage custom actions
/actionsList All Actions
List all registered actions for the organization
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/actionsRegister DB Action
Register a DB action for database queries (MySQL, Postgres, MongoDB, Neo4j)
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"action_name": "get_pending_orders",
"kind": "db",
"description": "Fetch pending orders from database",
"datasource": "orgconfig:db:orders_pg",
"query": "SELECT * FROM orders WHERE status = $1 AND created_at > $2",
"params": [
"pending",
"@input.since_date"
],
"passthrough": true,
"outputKey": "orders"
}Responses
/actions/{actionId}Get Action by ID
Get details of a specific registered action
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
actionId* | path | string | — |
Responses
/actions/{actionId}Update Action
Update an existing registered action
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
actionId* | path | string | — |
Request Body
Content-Type: application/json
{
"action_name": "fetch_customer_data",
"kind": "http",
"description": "Fetch customer details from CRM (updated)",
"url": "https://api.example.com/v2/customers",
"http_method": "GET",
"passthrough": true
}Responses
Agents
Standalone AI agent execution
/agentsList Agent Runs by Status
List agent runs filtered by status (running, paused, completed, failed)
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
status | query | string | — |
Responses
/agents/executeExecute Agent (Async)
Execute an agent asynchronously and poll for status
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
async | query | string | — |
Request Body
Content-Type: application/json
{
"objective": "Process all pending invoices and reconcile with payments",
"tools": [
"fetch_pending_invoices",
"fetch_payments",
"match_records",
"__run_workflow__",
"__complete__"
],
"config": {
"max_iterations": 20,
"timeout_ms": 600000
}
}Responses
/agents/{agentRunId}Cancel Agent
Cancel a running agent
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
agentRunId* | path | string | — |
Responses
/agents/{agentRunId}/resumeResume Paused Agent
Resume a paused agent with human input
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
agentRunId* | path | string | — |
Request Body
Content-Type: application/json
{
"human_input": "Proceed with the 10% discount compensation. Customer is a VIP.",
"approved": true
}Responses
/agents/{agentRunId}/statusGet Agent Status with Trace
Get agent status including full reasoning trace
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
agentRunId* | path | string | — |
include_trace | query | string | — |
Responses
/agents/{agentRunId}/traceGet Agent Reasoning Trace
Get full reasoning trace for an agent run (audit trail)
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
agentRunId* | path | string | — |
Responses
AI Generation
AI-powered workflow generation from natural language
/ai/generate-workflowInitiate AI Generation
Submit natural language description for AI workflow generation
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"prompt": "Create a workflow that processes incoming invoices. For each invoice, match it against our payment records. If a match is found, mark both as reconciled. If no match is found after 3 days, send an email reminder to the vendor. For invoices over $10,000, require manager approval before processing.",
"llmOptions": {
"model": "gpt-4",
"temperature": 0.7
}
}Responses
/ai/generate-workflow/{generationId}Get Generated Workflow
Retrieve the AI-generated workflow specification
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
generationId* | path | string | — |
Responses
/ai/generate-workflow/{generationId}/statusGet Generation Status
Check status of AI generation request
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
generationId* | path | string | — |
Responses
/workflows/create-from-aiCreate Workflow from AI Output
Create workflow, actions, and tables from AI-generated specification
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"hyphen_workflow_definition": {
"name": "ai_generated_invoice_processor",
"definition": {
"actions": [
{
"type": "matcher",
"properties": {
"left": "@input.invoices",
"right": "@input.payments",
"matchOn": [
"invoice_id"
]
}
}
]
}
},
"actions_to_register": [],
"custom_tables_to_create": [],
"workflow_description": "AI-generated invoice processing workflow",
"has_exception": false
}Responses
/workflows/generation-status/{processId}Get Creation Process Status
Get status of workflow creation process
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
processId* | path | string | — |
Responses
Approvals
Human-in-the-loop approval management
/approvals/{runId}List Pending Approvals
List all approval requests for a workflow run
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
runId* | path | string | — |
Responses
/approvals/{runId}/{stepIndex}Submit Approval
Submit approval for a paused workflow step
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
runId* | path | string | — |
stepIndex* | path | integer | Step index of the approval step in the workflow |
Request Body
Content-Type: application/json
{
"approved": true,
"comments": "Reviewed and approved",
"data": {
"reviewer": "[email protected]",
"notes": "All documentation verified"
}
}Responses
Health
Health check and discovery
/builtin-actionsList Built-in Actions
List all pre-registered OAuth business tools:
- Gmail: send, read, reply
- Slack: post, read_channel, dm
- Outlook: send, read, calendar_create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/healthHealth Check
Verify API is running and healthy
Responses
Custom Tables
Multi-tenant data storage
/custom-tablesCreate Custom Table
Create a new custom table
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"name": "{{customTableName}}",
"fields": [
{
"name": "record_id",
"type": "text",
"required": true
},
{
"name": "customer_id",
"type": "text",
"required": true
},
{
"name": "amount",
"type": "numeric",
"required": false
},
{
"name": "status",
"type": "text",
"required": true
},
{
"name": "processed",
"type": "boolean",
"required": false
},
{
"name": "created_at",
"type": "timestamptz",
"required": false
}
]
}Responses
/custom-tables/{customTableName}View Table Data
View all data in a custom table
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
customTableName* | path | string | — |
Responses
/custom-tables/{customTableName}Drop Custom Table
Delete a custom table
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
customTableName* | path | string | — |
Responses
/custom-tables/{customTableName}/auditView Table Audit Log
View audit log for a custom table
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
customTableName* | path | string | — |
Responses
/custom-tables/{customTableName}/bulk-insertBulk Insert Records
Insert multiple records at once
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
customTableName* | path | string | — |
Request Body
Content-Type: application/json
{
"records": [
{
"record_id": "rec-002",
"customer_id": "cust-456",
"amount": 2000,
"status": "pending"
},
{
"record_id": "rec-003",
"customer_id": "cust-789",
"amount": 750.25,
"status": "completed"
}
]
}Responses
/custom-tables/{customTableName}/insertInsert Record
Insert a single record into a custom table
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
customTableName* | path | string | — |
Request Body
Content-Type: application/json
{
"record_id": "rec-001",
"customer_id": "cust-123",
"amount": 1500.5,
"status": "pending",
"processed": false
}Responses
/custom-tables/{customTableName}/updateUpdate Records
Update records matching criteria
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
customTableName* | path | string | — |
Request Body
Content-Type: application/json
{
"where": {
"record_id": "rec-001"
},
"data": {
"status": "completed",
"processed": true
}
}Responses
External Forms
External-facing form management
/external-formsList Forms
List all external forms
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/external-formsCreate External Form
Create an external form
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"name": "Customer Feedback Form",
"description": "Collect customer feedback after purchase",
"fields": [
{
"name": "rating",
"type": "number",
"required": true,
"min": 1,
"max": 5
},
{
"name": "feedback",
"type": "text",
"required": false,
"maxLength": 1000
},
{
"name": "would_recommend",
"type": "boolean",
"required": true
}
],
"settings": {
"allow_multiple_submissions": false,
"require_authentication": false
}
}Responses
/external-forms/{formId}Get Form
Get form details
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
formId* | path | string | — |
Responses
/external-forms/{formId}Update Form
Update an external form
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
formId* | path | string | — |
Request Body
Content-Type: application/json
{
"name": "Customer Feedback Form v2",
"description": "Updated feedback form"
}Responses
/external-forms/{formId}Delete Form
Delete an external form
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
formId* | path | string | — |
Responses
/external-forms/{formId}/analyticsGet Form Analytics
Get analytics for a form
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
formId* | path | string | — |
Responses
/external-forms/{formId}/submissionsGet Form Submissions
Get all submissions for a form
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
formId* | path | string | — |
Responses
/external-forms/{formId}/submitSubmit Form
Submit a form response
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
formId* | path | string | — |
Request Body
Content-Type: application/json
{
"rating": 5,
"feedback": "Great service, very satisfied!",
"would_recommend": true
}Responses
Internal Forms
Workflow-bound form submissions (PbotForm)
/forms/pendingList Pending Forms
List all pending form requests
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/forms/{runId}/{stepIndex}/submitSubmit Form Data
Submit form data for a paused PbotForm step
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
runId* | path | string | — |
stepIndex* | path | integer | Step index of the PbotForm step |
Request Body
Content-Type: application/json
{
"shipping_address": "123 Main St, City, ST 12345",
"delivery_date": "2025-02-15",
"special_instructions": "Leave at door"
}Responses
OAuth
OAuth business tool integrations
/oauth/connectionsList OAuth Connections
List all OAuth connections for the organization
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/oauth/connections/{oauthProvider}/{accountEmail}Validate OAuth Connection
Validate a specific OAuth connection
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
oauthProvider* | path | string | — |
accountEmail* | path | string | Email of the connected OAuth account |
Responses
/oauth/connections/{oauthProvider}/{accountEmail}Remove OAuth Connection
Remove an OAuth connection
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
oauthProvider* | path | string | — |
accountEmail* | path | string | Email of the connected OAuth account |
Responses
/oauth/connections/{oauthProvider}/{accountEmail}/refreshRefresh OAuth Token
Force refresh an OAuth token
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
oauthProvider* | path | string | — |
accountEmail* | path | string | Email of the connected OAuth account |
Responses
/oauth/providersList OAuth Providers
List available OAuth providers and their configuration status
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/oauth/{oauthProvider}/app-credentialsCheck OAuth App Credentials
Check if OAuth app credentials are configured (doesn't return secrets)
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
oauthProvider* | path | string | — |
Responses
/oauth/{oauthProvider}/app-credentialsStore OAuth App Credentials
Store OAuth app credentials (clientid, clientsecret) for a provider
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
oauthProvider* | path | string | — |
Request Body
Content-Type: application/json
{
"client_id": "your-google-client-id.apps.googleusercontent.com",
"client_secret": "your-google-client-secret"
}Responses
/oauth/{oauthProvider}/authorizeGet Authorization URL
Get OAuth authorization URL to redirect user for consent
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
oauthProvider* | path | string | — |
return_url | query | string | — |
Responses
Org Config
Organization-level configuration and secrets
/org-configList All Config
List all configuration keys for the organization (values are masked)
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/org-configUpsert Config Key
Store or update a configuration key for the organization
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"key": "api:llm_api_key",
"value": "sk-test-key-replace-with-real"
}Responses
Execution
Execute workflows and check run status
/runs/{runId}/statusGet Run Status
Get current status of a workflow run including context and step details
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
runId* | path | string | — |
Responses
/workflows/{workflowId}/executeExecute Workflow
Execute a workflow with input payload
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
workflowId* | path | string | — |
Request Body
Content-Type: application/json
{
"customer_id": "cust-12345",
"invoice_id": "inv-67890",
"amount": 1500
}Responses
Schemas
JSON schema registry
/schemasCreate Schema
Register a JSON schema
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"name": "invoice_schema",
"schema": {
"type": "object",
"properties": {
"invoice_id": {
"type": "string"
},
"amount": {
"type": "number"
},
"vendor_id": {
"type": "string"
},
"due_date": {
"type": "string",
"format": "date"
}
},
"required": [
"invoice_id",
"amount"
]
}
}Responses
/schemas/{schemaName}Get Schema
Retrieve a registered schema
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
schemaName* | path | string | Name of the registered schema |
Responses
Utilities
Utility endpoints
/utils/generate-dagGenerate Workflow DAG
Generate DAG visualization data from workflow definition
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"actions": [
{
"type": "fetch_data",
"properties": {}
},
{
"type": "matcher",
"properties": {
"left": "@data1",
"right": "@data2"
}
},
{
"type": "process_results",
"properties": {}
}
]
}Responses
Workflows
Create and manage workflow definitions
/workflowsList All Workflows
List all workflow definitions for the organization
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Responses
/workflowsCreate Workflow with ReAct Agent
Create a workflow with ReAct agent for AI-powered reasoning
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — |
Request Body
Content-Type: application/json
{
"name": "intelligent_expense_reviewer",
"definition": {
"actions": [
{
"type": "loop",
"properties": {
"mode": "react",
"objective": "Review this expense report. Check policy compliance, verify the receipt, and determine if it should be approved, rejected, or escalated to a manager.",
"tools": [
"lookup_employee",
"check_expense_policy",
"verify_receipt",
"gmail_send",
"__pause_for_human__",
"__complete__"
],
"model": "gpt-4",
"max_iterations": 15,
"timeout_ms": 300000,
"temperature": 0.7,
"on_stuck": {
"action": "escalate",
"iterations": 3
},
"include_reasoning_trace": true,
"result_key": "expenseDecision"
}
},
{
"type": "process_expense",
"filter": {
"condition": {
"equal": [
"@expenseDecision.answer.decision",
"approved"
]
}
},
"properties": {
"expense_id": "@input.expense_id"
}
}
]
}
}Responses
/workflows/{workflowId}Get Workflow by ID
Get details of a specific workflow
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
workflowId* | path | string | — |
Responses
/workflows/{workflowId}Update Workflow
Update an existing workflow definition
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
workflowId* | path | string | — |
Request Body
Content-Type: application/json
{
"name": "simple_invoice_processor_v2",
"definition": {
"actions": [
{
"type": "fetch_customer_data",
"properties": {
"customer_id": "@input.customer_id"
}
}
]
}
}Responses
/workflows/{workflowId}Delete Workflow
Delete a workflow definition
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
| string | — | |
workflowId* | path | string | — |