Skip to main content
GET
/
health
HTTP API Overview
curl --request GET \
  --url https://your-worker.workers.dev/health

​
Overview

Conductor provides a RESTful HTTP API for executing ensembles, managing workflows, and monitoring system health. All endpoints return JSON responses.

​
Base URL

Configure your Conductor worker URL: 
# Development
https://conductor-dev.your-domain.workers.dev

# Staging
https://conductor-staging.your-domain.workers.dev

# Production
https://conductor.your-domain.workers.dev

​
Authentication

curl https://your-worker.workers.dev/api/v1/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Configure in wrangler.toml: 
[vars]
API_KEY_ENABLED = "true"
Add API key as secret: 
echo "your-secret-key" | npx wrangler secret put API_KEY

​
No Authentication (Development)

For development/testing, you can disable authentication: 
[vars]
API_KEY_ENABLED = "false"

​
Request Format

All POST requests accept JSON: 
{
  "ensemble": "workflow-name",
  "input": {
    "key": "value"
  }
}

​
Response Format

​
Success Response

{
  "id": "exec_abc123",
  "status": "completed",
  "output": {
    "result": "data"
  },
  "duration": 1523,
  "timestamp": 1234567890
}

​
Error Response

{
  "error": {
    "code": "ENSEMBLE_NOT_FOUND",
    "message": "Ensemble 'workflow-name' not found",
    "details": {}
  }
}

​
Status Codes

CodeMeaning
200Success
201Created
400Bad Request - Invalid input
401Unauthorized - Missing/invalid API key
404Not Found - Ensemble/resource not found
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable

​
Rate Limiting

Default rate limits per API key:
  • Execution: 1000 requests/minute
  • Queries: 10000 requests/minute
Rate limit headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1234567890

​
Pagination

List endpoints support pagination: 
GET /api/v1/members?page=1&limit=50
Response includes pagination metadata: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

​
Versioning

API version is included in the URL path:
  • Current: /api/v1/...
  • Future: /api/v2/... (maintains v1 compatibility)

​
CORS

CORS is enabled by default for all origins in development. Configure in production: 
// src/index.ts
const corsHeaders = {
  'Access-Control-Allow-Origin': 'https://your-app.com',
  'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
  'Access-Control-Max-Age': '86400'
};

​
Webhooks

Conductor can trigger external webhooks on events: 
# ensemble.yaml
flow:
  - member: notify-webhook
    type: API
    config:
      url: "${env.WEBHOOK_URL}"
      method: POST
    input:
      event: "workflow.completed"
      data: ${output}

​
SDKs

​
JavaScript/TypeScript

npm install @ensemble-edge/conductor

import { ConductorClient } from '@ensemble-edge/conductor/sdk';

const client = new ConductorClient({
  baseURL: 'https://your-worker.workers.dev',
  apiKey: process.env.CONDUCTOR_API_KEY
});

const result = await client.execute({
  ensemble: 'my-workflow',
  input: { data: 'test' }
});

​
cURL Examples

All endpoints include cURL examples for testing.

​
OpenAPI Specification

Download the OpenAPI spec: 
# Generate from deployed worker
curl https://your-worker.workers.dev/api/v1/openapi.json > openapi.json

# Or generate locally
npx conductor docs generate --type openapi
Import into tools:
  • Postman
  • Insomnia
  • Swagger UI
  • API testing tools

​
Endpoints

Execution API

Execute and manage workflows

Members API

List and inspect members

Schedules API

Manage cron schedules

Webhooks API

Trigger workflows via webhooks

Health API

Health checks and status

​
Best Practices

  1. Use API keys in production - Never disable authentication
  2. Implement retry logic - Handle transient failures (429, 500, 503)
  3. Cache responses - Reduce API calls for expensive operations
  4. Monitor rate limits - Track X-RateLimit headers
  5. Use webhooks for async - Don’t poll for status
  6. Validate input - Check before sending requests
  7. Handle errors gracefully - Parse error responses
  8. Set timeouts - Don’t wait indefinitely
  9. Log requests - Track API usage
  10. Version your clients - Pin SDK versions

​
Support