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.

Version 2.0.0 Base URL: http://localhost:3009

Actions

Register and manage custom actions

GET/actions

List All Actions

List all registered actions for the organization

Parameters

NameLocationTypeDescription
string—

Responses

200Success
POST/actions

Register DB Action

Register a DB action for database queries (MySQL, Postgres, MongoDB, Neo4j)

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/actions/{actionId}

Get Action by ID

Get details of a specific registered action

Parameters

NameLocationTypeDescription
string—
actionId*pathstring—

Responses

200Success
PUT/actions/{actionId}

Update Action

Update an existing registered action

Parameters

NameLocationTypeDescription
string—
actionId*pathstring—

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

200Success

Agents

Standalone AI agent execution

GET/agents

List Agent Runs by Status

List agent runs filtered by status (running, paused, completed, failed)

Parameters

NameLocationTypeDescription
string—
statusquerystring—

Responses

200Success
POST/agents/execute

Execute Agent (Async)

Execute an agent asynchronously and poll for status

Parameters

NameLocationTypeDescription
string—
asyncquerystring—

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

200Success
201Created
DELETE/agents/{agentRunId}

Cancel Agent

Cancel a running agent

Parameters

NameLocationTypeDescription
string—
agentRunId*pathstring—

Responses

200Success
POST/agents/{agentRunId}/resume

Resume Paused Agent

Resume a paused agent with human input

Parameters

NameLocationTypeDescription
string—
agentRunId*pathstring—

Request Body

Content-Type: application/json

{
  "human_input": "Proceed with the 10% discount compensation. Customer is a VIP.",
  "approved": true
}

Responses

200Success
201Created
GET/agents/{agentRunId}/status

Get Agent Status with Trace

Get agent status including full reasoning trace

Parameters

NameLocationTypeDescription
string—
agentRunId*pathstring—
include_tracequerystring—

Responses

200Success
GET/agents/{agentRunId}/trace

Get Agent Reasoning Trace

Get full reasoning trace for an agent run (audit trail)

Parameters

NameLocationTypeDescription
string—
agentRunId*pathstring—

Responses

200Success

AI Generation

AI-powered workflow generation from natural language

POST/ai/generate-workflow

Initiate AI Generation

Submit natural language description for AI workflow generation

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/ai/generate-workflow/{generationId}

Get Generated Workflow

Retrieve the AI-generated workflow specification

Parameters

NameLocationTypeDescription
string—
generationId*pathstring—

Responses

200Success
GET/ai/generate-workflow/{generationId}/status

Get Generation Status

Check status of AI generation request

Parameters

NameLocationTypeDescription
string—
generationId*pathstring—

Responses

200Success
POST/workflows/create-from-ai

Create Workflow from AI Output

Create workflow, actions, and tables from AI-generated specification

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/workflows/generation-status/{processId}

Get Creation Process Status

Get status of workflow creation process

Parameters

NameLocationTypeDescription
string—
processId*pathstring—

Responses

200Success

Approvals

Human-in-the-loop approval management

GET/approvals/{runId}

List Pending Approvals

List all approval requests for a workflow run

Parameters

NameLocationTypeDescription
string—
runId*pathstring—

Responses

200Success
POST/approvals/{runId}/{stepIndex}

Submit Approval

Submit approval for a paused workflow step

Parameters

NameLocationTypeDescription
string—
runId*pathstring—
stepIndex*pathintegerStep 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

200Success
201Created

Health

Health check and discovery

GET/builtin-actions

List 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

NameLocationTypeDescription
string—

Responses

200Success
GET/health

Health Check

Verify API is running and healthy

Responses

200Success

Custom Tables

Multi-tenant data storage

POST/custom-tables

Create Custom Table

Create a new custom table

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/custom-tables/{customTableName}

View Table Data

View all data in a custom table

Parameters

NameLocationTypeDescription
string—
customTableName*pathstring—

Responses

200Success
DELETE/custom-tables/{customTableName}

Drop Custom Table

Delete a custom table

Parameters

NameLocationTypeDescription
string—
customTableName*pathstring—

Responses

200Success
GET/custom-tables/{customTableName}/audit

View Table Audit Log

View audit log for a custom table

Parameters

NameLocationTypeDescription
string—
customTableName*pathstring—

Responses

200Success
POST/custom-tables/{customTableName}/bulk-insert

Bulk Insert Records

Insert multiple records at once

Parameters

NameLocationTypeDescription
string—
customTableName*pathstring—

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

200Success
201Created
POST/custom-tables/{customTableName}/insert

Insert Record

Insert a single record into a custom table

Parameters

NameLocationTypeDescription
string—
customTableName*pathstring—

Request Body

Content-Type: application/json

{
  "record_id": "rec-001",
  "customer_id": "cust-123",
  "amount": 1500.5,
  "status": "pending",
  "processed": false
}

Responses

200Success
201Created
PUT/custom-tables/{customTableName}/update

Update Records

Update records matching criteria

Parameters

NameLocationTypeDescription
string—
customTableName*pathstring—

Request Body

Content-Type: application/json

{
  "where": {
    "record_id": "rec-001"
  },
  "data": {
    "status": "completed",
    "processed": true
  }
}

Responses

200Success

External Forms

External-facing form management

GET/external-forms

List Forms

List all external forms

Parameters

NameLocationTypeDescription
string—

Responses

200Success
POST/external-forms

Create External Form

Create an external form

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/external-forms/{formId}

Get Form

Get form details

Parameters

NameLocationTypeDescription
string—
formId*pathstring—

Responses

200Success
PUT/external-forms/{formId}

Update Form

Update an external form

Parameters

NameLocationTypeDescription
string—
formId*pathstring—

Request Body

Content-Type: application/json

{
  "name": "Customer Feedback Form v2",
  "description": "Updated feedback form"
}

Responses

200Success
DELETE/external-forms/{formId}

Delete Form

Delete an external form

Parameters

NameLocationTypeDescription
string—
formId*pathstring—

Responses

200Success
GET/external-forms/{formId}/analytics

Get Form Analytics

Get analytics for a form

Parameters

NameLocationTypeDescription
string—
formId*pathstring—

Responses

200Success
GET/external-forms/{formId}/submissions

Get Form Submissions

Get all submissions for a form

Parameters

NameLocationTypeDescription
string—
formId*pathstring—

Responses

200Success
POST/external-forms/{formId}/submit

Submit Form

Submit a form response

Parameters

NameLocationTypeDescription
string—
formId*pathstring—

Request Body

Content-Type: application/json

{
  "rating": 5,
  "feedback": "Great service, very satisfied!",
  "would_recommend": true
}

Responses

200Success
201Created

Internal Forms

Workflow-bound form submissions (PbotForm)

GET/forms/pending

List Pending Forms

List all pending form requests

Parameters

NameLocationTypeDescription
string—

Responses

200Success
POST/forms/{runId}/{stepIndex}/submit

Submit Form Data

Submit form data for a paused PbotForm step

Parameters

NameLocationTypeDescription
string—
runId*pathstring—
stepIndex*pathintegerStep 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

200Success
201Created

OAuth

OAuth business tool integrations

GET/oauth/connections

List OAuth Connections

List all OAuth connections for the organization

Parameters

NameLocationTypeDescription
string—

Responses

200Success
GET/oauth/connections/{oauthProvider}/{accountEmail}

Validate OAuth Connection

Validate a specific OAuth connection

Parameters

NameLocationTypeDescription
string—
oauthProvider*pathstring—
accountEmail*pathstringEmail of the connected OAuth account

Responses

200Success
DELETE/oauth/connections/{oauthProvider}/{accountEmail}

Remove OAuth Connection

Remove an OAuth connection

Parameters

NameLocationTypeDescription
string—
oauthProvider*pathstring—
accountEmail*pathstringEmail of the connected OAuth account

Responses

200Success
POST/oauth/connections/{oauthProvider}/{accountEmail}/refresh

Refresh OAuth Token

Force refresh an OAuth token

Parameters

NameLocationTypeDescription
string—
oauthProvider*pathstring—
accountEmail*pathstringEmail of the connected OAuth account

Responses

200Success
201Created
GET/oauth/providers

List OAuth Providers

List available OAuth providers and their configuration status

Parameters

NameLocationTypeDescription
string—

Responses

200Success
GET/oauth/{oauthProvider}/app-credentials

Check OAuth App Credentials

Check if OAuth app credentials are configured (doesn't return secrets)

Parameters

NameLocationTypeDescription
string—
oauthProvider*pathstring—

Responses

200Success
POST/oauth/{oauthProvider}/app-credentials

Store OAuth App Credentials

Store OAuth app credentials (clientid, clientsecret) for a provider

Parameters

NameLocationTypeDescription
string—
oauthProvider*pathstring—

Request Body

Content-Type: application/json

{
  "client_id": "your-google-client-id.apps.googleusercontent.com",
  "client_secret": "your-google-client-secret"
}

Responses

200Success
201Created
GET/oauth/{oauthProvider}/authorize

Get Authorization URL

Get OAuth authorization URL to redirect user for consent

Parameters

NameLocationTypeDescription
string—
oauthProvider*pathstring—
return_urlquerystring—

Responses

200Success

Org Config

Organization-level configuration and secrets

GET/org-config

List All Config

List all configuration keys for the organization (values are masked)

Parameters

NameLocationTypeDescription
string—

Responses

200Success
POST/org-config

Upsert Config Key

Store or update a configuration key for the organization

Parameters

NameLocationTypeDescription
string—

Request Body

Content-Type: application/json

{
  "key": "api:llm_api_key",
  "value": "sk-test-key-replace-with-real"
}

Responses

200Success
201Created

Execution

Execute workflows and check run status

GET/runs/{runId}/status

Get Run Status

Get current status of a workflow run including context and step details

Parameters

NameLocationTypeDescription
string—
runId*pathstring—

Responses

200Success
POST/workflows/{workflowId}/execute

Execute Workflow

Execute a workflow with input payload

Parameters

NameLocationTypeDescription
string—
workflowId*pathstring—

Request Body

Content-Type: application/json

{
  "customer_id": "cust-12345",
  "invoice_id": "inv-67890",
  "amount": 1500
}

Responses

200Success
201Created

Schemas

JSON schema registry

POST/schemas

Create Schema

Register a JSON schema

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/schemas/{schemaName}

Get Schema

Retrieve a registered schema

Parameters

NameLocationTypeDescription
string—
schemaName*pathstringName of the registered schema

Responses

200Success

Utilities

Utility endpoints

POST/utils/generate-dag

Generate Workflow DAG

Generate DAG visualization data from workflow definition

Parameters

NameLocationTypeDescription
string—

Request Body

Content-Type: application/json

{
  "actions": [
    {
      "type": "fetch_data",
      "properties": {}
    },
    {
      "type": "matcher",
      "properties": {
        "left": "@data1",
        "right": "@data2"
      }
    },
    {
      "type": "process_results",
      "properties": {}
    }
  ]
}

Responses

200Success
201Created

Workflows

Create and manage workflow definitions

GET/workflows

List All Workflows

List all workflow definitions for the organization

Parameters

NameLocationTypeDescription
string—

Responses

200Success
POST/workflows

Create Workflow with ReAct Agent

Create a workflow with ReAct agent for AI-powered reasoning

Parameters

NameLocationTypeDescription
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

200Success
201Created
GET/workflows/{workflowId}

Get Workflow by ID

Get details of a specific workflow

Parameters

NameLocationTypeDescription
string—
workflowId*pathstring—

Responses

200Success
PUT/workflows/{workflowId}

Update Workflow

Update an existing workflow definition

Parameters

NameLocationTypeDescription
string—
workflowId*pathstring—

Request Body

Content-Type: application/json

{
  "name": "simple_invoice_processor_v2",
  "definition": {
    "actions": [
      {
        "type": "fetch_customer_data",
        "properties": {
          "customer_id": "@input.customer_id"
        }
      }
    ]
  }
}

Responses

200Success
DELETE/workflows/{workflowId}

Delete Workflow

Delete a workflow definition

Parameters

NameLocationTypeDescription
string—
workflowId*pathstring—

Responses

200Success