Workflows

Create, manage, and execute custom AI workflows programmatically. Workflows allow you to chain multiple AI operations together for complex automation.

Workflow Management

List Workflows

Get all workflows accessible to your account:

GET /api/v1/workflows

Query Parameters:

• limit (optional): Number of workflows to return (default: 20)

• offset (optional): Number of workflows to skip (default: 0)

• category (optional): Filter by workflow category

• public (optional): Include public workflows (default: false)

Response:

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Content Marketing Pipeline",
      "description": "Generate marketing content from product descriptions",
      "category": "marketing",
      "public": true,
      "created_by": "user_xyz789",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "usage_count": 156,
      "rating": 4.8
    }
  ],
  "total": 1,
  "has_more": false
}

Get Workflow Details

Retrieve detailed information about a specific workflow:

GET /api/v1/workflows/{workflow_id}

Response:

{
  "id": "wf_abc123",
  "name": "Content Marketing Pipeline",
  "description": "Generate comprehensive marketing content from product descriptions",
  "category": "marketing",
  "public": true,
  "created_by": "user_xyz789",
  "nodes": [
    {
      "id": "node_1",
      "type": "input",
      "config": {
        "name": "product_description",
        "type": "text",
        "required": true
      }
    },
    {
      "id": "node_2",
      "type": "ai_model",
      "config": {
        "model": "gpt-4",
        "prompt": "Generate 5 marketing headlines for: {{product_description}}",
        "max_tokens": 200
      }
    },
    {
      "id": "node_3",
      "type": "ai_model",
      "config": {
        "model": "claude-3",
        "prompt": "Create detailed product copy based on: {{product_description}}",
        "max_tokens": 500
      }
    },
    {
      "id": "node_4",
      "type": "output",
      "config": {
        "format": "json",
        "fields": ["headlines", "product_copy"]
      }
    }
  ],
  "connections": [
    {"from": "node_1", "to": "node_2"},
    {"from": "node_1", "to": "node_3"},
    {"from": "node_2", "to": "node_4"},
    {"from": "node_3", "to": "node_4"}
  ]
}

Creating Workflows

Create New Workflow

Create a new workflow with defined nodes and connections:

POST /api/v1/workflows

Request Body:

{
  "name": "Research Assistant",
  "description": "Automated research and summary generation",
  "category": "research",
  "public": false,
  "nodes": [
    {
      "id": "input_topic",
      "type": "input",
      "config": {
        "name": "research_topic",
        "type": "text",
        "required": true,
        "description": "Topic to research"
      }
    },
    {
      "id": "research_gpt",
      "type": "ai_model",
      "config": {
        "model": "gpt-4",
        "prompt": "Research the topic: {{research_topic}}. Provide key facts and insights.",
        "max_tokens": 800
      }
    },
    {
      "id": "analyze_claude",
      "type": "ai_model",
      "config": {
        "model": "claude-3",
        "prompt": "Analyze this research: {{research_gpt.output}}. Identify main themes and conclusions.",
        "max_tokens": 400
      }
    },
    {
      "id": "final_output",
      "type": "output",
      "config": {
        "format": "markdown",
        "template": "# Research Summary: {{research_topic}}\n\n## Key Findings\n{{research_gpt.output}}\n\n## Analysis\n{{analyze_claude.output}}"
      }
    }
  ],
  "connections": [
    {"from": "input_topic", "to": "research_gpt"},
    {"from": "research_gpt", "to": "analyze_claude"},
    {"from": "analyze_claude", "to": "final_output"}
  ]
}

Response:

{
  "id": "wf_def456",
  "name": "Research Assistant",
  "status": "created",
  "created_at": "2024-01-21T09:15:00Z"
}

Update Workflow

Modify an existing workflow:

PUT /api/v1/workflows/{workflow_id}

Request Body: (Same structure as create, with modifications)

Delete Workflow

Remove a workflow from your account:

DELETE /api/v1/workflows/{workflow_id}

Executing Workflows

Execute Workflow

Run a workflow with provided inputs:

POST /api/v1/workflows/{workflow_id}/execute

Request Body:

{
  "inputs": {
    "research_topic": "Artificial Intelligence in Healthcare"
  },
  "options": {
    "async": false,
    "webhook_url": "https://your-app.com/webhook"
  }
}

Synchronous Response:

{
  "execution_id": "exec_ghi789",
  "status": "completed",
  "started_at": "2024-01-21T10:00:00Z",
  "completed_at": "2024-01-21T10:02:30Z",
  "outputs": {
    "final_output": "# Research Summary: Artificial Intelligence in Healthcare\n\n## Key Findings\nAI is transforming healthcare through...\n\n## Analysis\nThe main themes include..."
  },
  "usage": {
    "total_tokens": 1200,
    "tokens_earned": 15
  }
}

Asynchronous Response:

{
  "execution_id": "exec_ghi789",
  "status": "running",
  "started_at": "2024-01-21T10:00:00Z",
  "estimated_completion": "2024-01-21T10:03:00Z"
}

Get Execution Status

Check the status of a running workflow execution:

GET /api/v1/workflows/{workflow_id}/executions/{execution_id}

Response:

{
  "execution_id": "exec_ghi789",
  "workflow_id": "wf_def456",
  "status": "running",
  "progress": {
    "completed_nodes": 2,
    "total_nodes": 4,
    "current_node": "analyze_claude"
  },
  "started_at": "2024-01-21T10:00:00Z",
  "outputs": {
    "research_gpt": "AI in healthcare involves..."
  }
}

List Executions

Get execution history for a workflow:

GET /api/v1/workflows/{workflow_id}/executions

Response:

{
  "executions": [
    {
      "execution_id": "exec_ghi789",
      "status": "completed",
      "started_at": "2024-01-21T10:00:00Z",
      "completed_at": "2024-01-21T10:02:30Z",
      "tokens_used": 1200,
      "tokens_earned": 15
    }
  ],
  "total": 1
}

Node Types

Input Nodes

Collect user input for workflow execution:

{
  "type": "input",
  "config": {
    "name": "user_input",
    "type": "text|number|file|json",
    "required": true,
    "description": "Input description",
    "validation": {
      "min_length": 10,
      "max_length": 1000
    }
  }
}

AI Model Nodes

Execute AI model requests:

{
  "type": "ai_model",
  "config": {
    "model": "gpt-4|claude-3|gemini-pro",
    "prompt": "Template with {{variables}}",
    "max_tokens": 500,
    "temperature": 0.7,
    "system_message": "Optional system message"
  }
}

Processing Nodes

Transform and manipulate data:

{
  "type": "processor",
  "config": {
    "operation": "filter|transform|aggregate",
    "script": "JavaScript code for processing",
    "parameters": {}
  }
}

Conditional Nodes

Branch workflow execution based on conditions:

{
  "type": "condition",
  "config": {
    "condition": "{{input.length}} > 100",
    "true_path": "node_id_if_true",
    "false_path": "node_id_if_false"
  }
}

Output Nodes

Format and return workflow results:

{
  "type": "output",
  "config": {
    "format": "json|text|markdown|html",
    "template": "Output template with {{variables}}",
    "fields": ["field1", "field2"]
  }
}

Workflow Templates

Get Templates

Browse available workflow templates:

GET /api/v1/workflows/templates

Create from Template

Create a new workflow from a template:

POST /api/v1/workflows/from-template

Request Body:

{
  "template_id": "template_123",
  "name": "My Custom Workflow",
  "customizations": {
    "model_preferences": {
      "primary": "gpt-4",
      "secondary": "claude-3"
    }
  }
}

Error Handling

Workflow Execution Errors

{
  "execution_id": "exec_ghi789",
  "status": "failed",
  "error": {
    "code": "node_execution_failed",
    "message": "AI model request failed",
    "node_id": "research_gpt",
    "details": {
      "model_error": "Rate limit exceeded"
    }
  }
}

Validation Errors

{
  "error": {
    "code": "validation_error",
    "message": "Workflow validation failed",
    "details": {
      "invalid_connections": ["node_1 -> node_3"],
      "missing_required_fields": ["nodes[0].config.name"]
    }
  }
}

Best Practices

Workflow Design

• Keep workflows focused on specific tasks

• Use descriptive names and descriptions

• Include proper error handling nodes

• Test workflows thoroughly before publishing

Performance Optimization

• Minimize unnecessary AI model calls

• Use caching for repeated operations

• Implement parallel execution where possible

• Monitor token usage and costs

Security Considerations

• Validate all user inputs

• Sanitize data between nodes

• Use appropriate access controls

• Audit workflow executions regularly

The Workflows API will be available with our Q4 2025 developer ecosystem launch.