Skip to main content

AI Workflow API Reference

Complete API reference for AI Workflow.

Authentication​

All API requests require authentication using an API key:

Authorization: Bearer YOUR_API_KEY

Base URL​

https://api.aiworkflow.com/v1

Workflows​

List Workflows​

Retrieve a list of all workflows.

Request:

GET /api/v1/workflows
Authorization: Bearer YOUR_API_KEY

Response:

{
  "data": [
    {
      "id": "wf_123",
      "name": "Data Processing Workflow",
      "description": "Processes and analyzes data",
      "status": "active",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 100
  }
}

Create Workflow​

Create a new workflow.

Request:

POST /api/v1/workflows
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "New Workflow",
  "description": "Workflow description",
  "config": {
    "timeout": 30000,
    "retries": 3
  }
}

Response:

{
  "id": "wf_123",
  "name": "New Workflow",
  "description": "Workflow description",
  "status": "draft",
  "createdAt": "2024-01-01T00:00:00Z"
}

Get Workflow​

Retrieve a specific workflow by ID.

Parameters:

ParameterTypeDescription
idstringWorkflow identifier

Request:

GET /api/v1/workflows/wf_123
Authorization: Bearer YOUR_API_KEY

Response:

{
  "id": "wf_123",
  "name": "Data Processing Workflow",
  "description": "Processes and analyzes data",
  "status": "active",
  "steps": [
    {
      "id": "step_1",
      "name": "Data Ingestion",
      "type": "data-input",
      "order": 1
    },
    {
      "id": "step_2",
      "name": "AI Analysis",
      "type": "ai-process",
      "order": 2
    }
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Update Workflow​

Update an existing workflow.

Request:

PUT /api/v1/workflows/wf_123
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Updated Workflow Name",
  "description": "Updated description"
}

Response:

{
  "id": "wf_123",
  "name": "Updated Workflow Name",
  "description": "Updated description",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Delete Workflow​

Delete a workflow.

Request:

DELETE /api/v1/workflows/wf_123
Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "message": "Workflow deleted successfully"
}

Workflow Execution​

Execute Workflow​

Execute a workflow with input data.

Request:

POST /api/v1/workflows/wf_123/execute
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "input": {
    "data": "your input data"
  },
  "options": {
    "async": false,
    "timeout": 30000
  }
}

Response:

{
  "executionId": "exec_123",
  "workflowId": "wf_123",
  "status": "completed",
  "result": {
    "output": "processed data",
    "steps": [
      {
        "stepId": "step_1",
        "status": "completed",
        "result": "step result"
      }
    ]
  },
  "startedAt": "2024-01-01T00:00:00Z",
  "completedAt": "2024-01-01T00:00:05Z",
  "duration": 5000
}

Get Execution Status​

Get the status of a workflow execution.

Request:

GET /api/v1/executions/exec_123
Authorization: Bearer YOUR_API_KEY

Response:

{
  "executionId": "exec_123",
  "workflowId": "wf_123",
  "status": "running",
  "progress": 50,
  "currentStep": "step_2",
  "startedAt": "2024-01-01T00:00:00Z"
}

Workflow Steps​

Add Step to Workflow​

Add a step to an existing workflow.

Request:

POST /api/v1/workflows/wf_123/steps
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "New Step",
  "type": "ai-process",
  "order": 3,
  "config": {
    "model": "gpt-4",
    "prompt": "Process the data"
  }
}

Response:

{
  "id": "step_3",
  "name": "New Step",
  "type": "ai-process",
  "order": 3,
  "config": {
    "model": "gpt-4",
    "prompt": "Process the data"
  }
}

Error Responses​

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes​

CodeStatusDescription
UNAUTHORIZED401Invalid or missing API key
WORKFLOW_NOT_FOUND404Workflow not found
EXECUTION_FAILED500Workflow execution failed
VALIDATION_ERROR422Request validation failed
RATE_LIMIT_EXCEEDED429Too many requests

Rate Limiting​

API requests are rate-limited:

  • Free tier: 100 requests/hour
  • Pro tier: 1,000 requests/hour
  • Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

SDK Examples​

JavaScript/TypeScript​

import { AIWorkflow } from 'ai-workflow';

const workflow = new AIWorkflow({
  apiKey: process.env.API_KEY
});

// List all workflows
const workflows = await workflow.list();

// Create a workflow
const newWorkflow = await workflow.create({
  name: 'My Workflow',
  description: 'Workflow description'
});

// Execute workflow
const result = await workflow.execute(newWorkflow.id, {
  input: { data: 'test' }
});

// Get execution status
const status = await workflow.getExecution('exec_123');

Python​

from ai_workflow import AIWorkflow

client = AIWorkflow(api_key=os.getenv('API_KEY'))

# List all workflows
workflows = client.list_workflows()

# Create a workflow
workflow = client.create_workflow({
    'name': 'My Workflow',
    'description': 'Workflow description'
})

# Execute workflow
result = client.execute_workflow(workflow['id'], {
    'input': {'data': 'test'}
})

Next Steps​