API Reference

API Resources

Action Chains

Action Chains API

Action chains are automated workflows that execute a series of steps sequentially. They’re useful for complex, multi-step processes that need to be repeatable.

Chain Management

List Action Chains

GET /orgs/{organizationId}/chains

Query Parameters:

limit (optional): Number of results per page (default: 20)
cursor (optional): Pagination cursor

Create Action Chain

POST /orgs/{organizationId}/chains

Request Body:

{
  "name": "Customer Onboarding",
  "description": "Automated customer onboarding workflow",
  "enabled": true
}

Response: Returns the created chain with chainId

Get Chain

GET /orgs/{organizationId}/chains/{chainId}

Returns the chain configuration including all steps.

Update Chain

PUT /orgs/{organizationId}/chains/{chainId}

Request Body:

{
  "name": "Updated Onboarding Flow",
  "description": "Updated description",
  "enabled": true
}

Delete Chain

DELETE /orgs/{organizationId}/chains/{chainId}

Permanently deletes the chain and all its steps.

Executing Chains

Run Chain

POST /orgs/{organizationId}/chains/{chainId}/run

Execute a chain with input parameters.

Request Body:

{
  "input": {
    "customerEmail": "customer@example.com",
    "customerName": "John Doe",
    "accountType": "premium"
  }
}

Response:

{
  "runId": "run-123",
  "chainId": "chain-456",
  "status": "running",
  "startedAt": "2024-01-01T00:00:00Z"
}

List Chain Runs

GET /orgs/{organizationId}/chains/{chainId}/runs

Get execution history for a chain.

Query Parameters:

limit (optional): Number of results (default: 20)
status (optional): Filter by status (running, completed, failed)

Response:

{
  "items": [
    {
      "runId": "run-123",
      "chainId": "chain-456",
      "status": "completed",
      "startedAt": "2024-01-01T00:00:00Z",
      "completedAt": "2024-01-01T00:05:00Z",
      "input": { ... },
      "output": { ... }
    }
  ]
}

Chain Steps

List Steps

GET /orgs/{organizationId}/chains/{chainId}/steps

Returns all steps in the chain in execution order.

Create Step

POST /orgs/{organizationId}/chains/{chainId}/steps

Request Body:

{
  "name": "Send Welcome Email",
  "stepType": "agent",
  "order": 1,
  "config": {
    "agentId": "agent-123",
    "prompt": "Send a welcome email to {{customerEmail}}"
  }
}

Step Types:

agent - Execute an agent
api_call - Make an external API call
condition - Conditional branching
transform - Data transformation
wait - Wait for a duration or event

Get Step

GET /orgs/{organizationId}/chains/{chainId}/steps/{stepId}

Update Step

PUT /orgs/{organizationId}/chains/{chainId}/steps/{stepId}

Request Body:

{
  "name": "Updated Step Name",
  "order": 2,
  "config": {
    "agentId": "agent-456"
  }
}

Delete Step

DELETE /orgs/{organizationId}/chains/{chainId}/steps/{stepId}

Step Attachments

Steps can have agents, knowledge bases, and tools attached to them.

Attach Agent to Step

POST /orgs/{organizationId}/chains/{chainId}/steps/{stepId}/agents

Request Body:

{
  "agentId": "agent-123"
}

Detach Agent from Step

DELETE /orgs/{organizationId}/chains/{chainId}/steps/{stepId}/agents/{agentId}

Attach Knowledge Base to Step

POST /orgs/{organizationId}/chains/{chainId}/steps/{stepId}/knowledge-bases

Request Body:

{
  "knowledgeBaseId": "kb-123"
}

Detach Knowledge Base from Step

DELETE /orgs/{organizationId}/chains/{chainId}/steps/{stepId}/knowledge-bases/{kbId}

Attach Tool to Step

POST /orgs/{organizationId}/chains/{chainId}/steps/{stepId}/tools

Request Body:

{
  "toolCode": "calculator",
  "config": {
    "precision": 2
  }
}

Detach Tool from Step

DELETE /orgs/{organizationId}/chains/{chainId}/steps/{stepId}/tools/{toolCode}

Generate Chain from Prompt

POST /orgs/{organizationId}/chains/from-prompt

Automatically generate a chain configuration from a natural language description.

Request Body:

{
  "prompt": "Create a workflow that: 1) Receives a customer inquiry, 2) Checks if it's a technical issue, 3) If yes, creates a support ticket and notifies the technical team, 4) If no, routes to sales team"
}

Response: Returns a suggested chain configuration with steps.

Variables and Data Flow

Using Variables

Chain steps can reference variables from previous steps:

{
  "stepType": "agent",
  "config": {
    "prompt": "Send email to {{step1.customerEmail}} with subject {{step2.emailSubject}}"
  }
}

Variable Syntax

{{input.variableName}} - Access chain input
{{stepN.outputField}} - Access output from step N
{{env.API_KEY}} - Access environment variable (from vault)

Example Workflows

Customer Onboarding Chain

{
  "name": "Customer Onboarding",
  "steps": [
    {
      "name": "Validate Email",
      "stepType": "api_call",
      "order": 1,
      "config": {
        "url": "https://api.emailvalidation.com/validate",
        "method": "POST",
        "body": {
          "email": "{{input.customerEmail}}"
        }
      }
    },
    {
      "name": "Create Account",
      "stepType": "agent",
      "order": 2,
      "config": {
        "agentId": "agent-123",
        "prompt": "Create account for {{input.customerName}}"
      }
    },
    {
      "name": "Send Welcome Email",
      "stepType": "agent",
      "order": 3,
      "config": {
        "agentId": "agent-456",
        "prompt": "Send welcome email to {{input.customerEmail}}"
      }
    },
    {
      "name": "Notify Team",
      "stepType": "api_call",
      "order": 4,
      "config": {
        "url": "https://hooks.slack.com/webhook",
        "method": "POST",
        "body": {
          "text": "New customer onboarded: {{input.customerName}}"
        }
      }
    }
  ]
}

Support Ticket Routing

{
  "name": "Support Ticket Router",
  "steps": [
    {
      "name": "Analyze Issue",
      "stepType": "agent",
      "order": 1,
      "config": {
        "agentId": "triage-agent",
        "prompt": "Classify this issue: {{input.issueDescription}}"
      }
    },
    {
      "name": "Route Based on Type",
      "stepType": "condition",
      "order": 2,
      "config": {
        "condition": "step1.issueType === 'technical'",
        "ifTrue": {
          "stepId": "create-tech-ticket"
        },
        "ifFalse": {
          "stepId": "route-to-sales"
        }
      }
    }
  ]
}

Best Practices

Clear Naming - Use descriptive names for chains and steps
Error Handling - Add error handling steps for critical workflows
Testing - Test chains with sample data before production use
Monitoring - Review chain execution logs regularly
Modular Design - Keep steps focused on single responsibilities
Documentation - Document chain purpose and expected inputs/outputs

Monitoring and Debugging

Check Run Status

After executing a chain, poll the run status:

GET /orgs/{organizationId}/chains/{chainId}/runs/{runId}

View Step Outputs

Each completed step includes its output in the run details:

{
  "runId": "run-123",
  "steps": [
    {
      "stepId": "step-1",
      "status": "completed",
      "output": {
        "result": "Success",
        "data": { ... }
      }
    }
  ]
}

Common Issues

Issue	Solution
Step timeout	Increase timeout in step config
Missing variables	Check variable names and previous step outputs
Agent errors	Review agent logs and prompt configuration
API call failures	Verify endpoint URLs and credentials in vault

Knowledge Bases Tables