Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://your-worker.workers.dev/api/v1
Replace your-worker.workers.dev with your deployed Cloudflare Worker URL.

​
Authentication

All requests require authentication via Bearer token: 
Authorization: Bearer {your-api-token}

​
Execute Ensemble

Execute an ensemble workflow.

​
Request

POST /api/v1/execute/ensemble/{name}
Content-Type: application/json
Authorization: Bearer {token}

{
  "input": {
    "field1": "value1",
    "field2": "value2"
  }
}

​
Parameters

Path:
  • name (string, required) - Ensemble name
Body:
  • inputs (object, required) - Input data
  • options (object, optional) - Execution options
    • timeout (number) - Timeout in ms
    • enableTracing (boolean) - Enable tracing
    • enableCaching (boolean) - Enable caching

​
Response

{
  "id": "exec-abc123...",
  "status": "completed",
  "output": {
    "result": "success",
    "data": {...}
  },
  "duration": 1234,
  "timestamp": 1705315200000,
  "trace": {...}
}
Status Codes:
  • 200 - Success
  • 400 - Invalid request
  • 401 - Unauthorized
  • 403 - Forbidden (ensemble not executable via API)
  • 404 - Ensemble not found
  • 408 - Timeout
  • 500 - Server error

​
Access Control

Ensembles can be configured to allow or deny Execute API access using the apiExecutable flag: 
# ensemble.yaml
name: internal-workflow
apiExecutable: false  # Prevents API execution
Behavior:
  • By default, all ensembles are executable via the Execute API
  • Set apiExecutable: false to block API execution
  • For stricter control, set api.execution.ensembles.requireExplicit: true in conductor.config.ts to require explicit opt-in
See Security & Authentication for full configuration options.

​
Example

curl -X POST https://your-worker.workers.dev/api/v1/execute/ensemble/user-onboarding \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "email": "alice@example.com",
      "name": "Alice"
    }
  }'

​
Execute Agent

Execute a single agent directly.
Note: Direct agent execution must be enabled in your security configuration. See Security & Authentication.

​
Request

POST /api/v1/execute/agent/{name}
Content-Type: application/json
Authorization: Bearer {token}

{
  "input": {
    "company_name": "Anthropic"
  }
}

​
Response

{
  "output": {
    "company_data": {...}
  },
  "duration": 567,
  "operations": [
    {
      "name": "search",
      "operation": "http",
      "duration": 234,
      "cached": false
    }
  ]
}
Status Codes:
  • 200 - Success
  • 400 - Invalid request
  • 401 - Unauthorized
  • 403 - Forbidden (agent not executable via API or direct execution disabled)
  • 404 - Agent not found
  • 500 - Server error

​
Access Control

Agents can be configured to allow or deny Execute API access using the apiExecutable flag: 
# agents/sensitive-operation.yaml
name: sensitive-operation
operation: code
handler: ./handler.ts
apiExecutable: false  # Prevents API execution
Behavior:
  • By default, all agents are executable via the Execute API (if direct agent execution is enabled)
  • Set apiExecutable: false to block API execution
  • For stricter control, set api.execution.agents.requireExplicit: true in conductor.config.ts to require explicit opt-in
See Security & Authentication for full configuration options.

​
List Ensembles

Get all available ensembles.

​
Request

GET /api/v1/ensembles
Authorization: Bearer {token}
Query Parameters:
  • tags (string[]) - Filter by tags
  • search (string) - Search by name/description

​
Response

{
  "ensembles": [
    {
      "name": "user-onboarding",
      "description": "Onboard new users",
      "inputs": {
        "email": { "type": "string", "required": true },
        "name": { "type": "string", "required": true }
      },
      "outputs": {
        "userId": "string",
        "created": "boolean"
      },
      "version": "v1.2.0",
      "tags": ["user", "onboarding"]
    }
  ]
}

​
Get Ensemble

Get ensemble metadata.

​
Request

GET /api/v1/ensembles/{name}
Authorization: Bearer {token}

​
Response

{
  "name": "user-onboarding",
  "description": "Onboard new users",
  "inputs": {...},
  "outputs": {...},
  "agents": ["create-account", "send-welcome-email"],
  "version": "v1.2.0"
}

​
List Agents

Get all available agents.

​
Request

GET /api/v1/agents
Authorization: Bearer {token}

​
Response

{
  "agents": [
    {
      "name": "company-enricher",
      "description": "Enrich company data",
      "inputs": {...},
      "outputs": {...},
      "operations": ["search", "scrape", "extract"]
    }
  ]
}

​
Get Execution Status

Get execution status and details.

​
Request

GET /api/v1/executions/{id}
Authorization: Bearer {token}

​
Response

{
  "id": "exec-abc123...",
  "status": "running",
  "ensemble": "user-onboarding",
  "startTime": 1705315200000,
  "progress": {
    "completed": 2,
    "total": 5,
    "currentAgent": "send-welcome-email"
  }
}

​
Cancel Execution

Cancel a running execution.

​
Request

POST /api/v1/executions/{id}/cancel
Authorization: Bearer {token}

​
Response

{
  "cancelled": true,
  "executionId": "exec-abc123..."
}

​
List Executions

Get execution history.

​
Request

GET /api/v1/executions
Authorization: Bearer {token}
Query Parameters:
  • ensemble (string) - Filter by ensemble
  • status (string) - Filter by status
  • startTime (number) - Filter by start time
  • limit (number) - Limit results (default: 100)

​
Response

{
  "executions": [
    {
      "id": "exec-abc123...",
      "ensemble": "user-onboarding",
      "status": "completed",
      "duration": 1234,
      "timestamp": 1705315200000
    }
  ],
  "total": 1543,
  "hasMore": true,
  "nextCursor": "cursor-xyz..."
}

​
Get State

Get ensemble state.

​
Request

GET /api/v1/executions/{id}/state
Authorization: Bearer {token}

​
Response

{
  "state": {
    "counter": 5,
    "history": [...],
    "userPreferences": {...}
  },
  "lastModified": 1705315200000
}

​
Update State

Update ensemble state.

​
Request

PUT /api/v1/executions/{id}/state
Content-Type: application/json
Authorization: Bearer {token}

{
  "state": {
    "counter": 6,
    "history": [...]
  }
}

​
Response

{
  "updated": true
}

​
Get Logs

Get execution logs.

​
Request

GET /api/v1/executions/{id}/logs
Authorization: Bearer {token}
Query Parameters:
  • level (string) - Filter by log level
  • agent (string) - Filter by agent

​
Response

{
  "logs": [
    {
      "timestamp": 1705315200000,
      "level": "info",
      "agent": "create-account",
      "message": "Creating user account",
      "metadata": {...}
    }
  ]
}

​
Health Check

Check API health.

​
Request

GET /api/v1/health

​
Response

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 123456,
  "timestamp": 1705315200000
}

​
Error Response Format

All errors follow this format: 
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Missing required field: email",
    "details": {
      "field": "email",
      "expected": "string"
    }
  }
}
Error Codes:
  • INVALID_INPUT - Invalid request data
  • UNAUTHORIZED - Missing/invalid auth token
  • FORBIDDEN - Resource not accessible (e.g., apiExecutable: false)
  • NOT_FOUND - Resource not found
  • TIMEOUT - Execution timeout
  • RATE_LIMIT_EXCEEDED - Rate limit hit
  • INTERNAL_ERROR - Server error

​
Rate Limiting

Rate limits apply per API token: Headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705315200
When rate limited (429): 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retryAfter": 3600
  }
}

​
Pagination

List endpoints support cursor-based pagination: 
GET /api/v1/executions?limit=100&cursor=cursor-xyz...
Response includes: 
{
  "items": [...],
  "hasMore": true,
  "nextCursor": "cursor-abc..."
}

​
Next Steps

Authentication

API authentication

Webhooks

Webhook integration

Rate Limits

Rate limit details

TypeScript SDK

TypeScript API