> ## 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. # HTTP Endpoints > Complete REST API for ensemble execution and management ## 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: ```http theme={null} Authorization: Bearer {your-api-token} ``` ## Execute Ensemble Execute an ensemble workflow. ### Request ```http theme={null} 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 ```json theme={null} { "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: ```yaml theme={null} # 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](/conductor/building/security-authentication#api-execution-access-control) for full configuration options. ### Example ```bash theme={null} 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](/conductor/building/security-authentication). ### Request ```http theme={null} POST /api/v1/execute/agent/{name} Content-Type: application/json Authorization: Bearer {token} { "input": { "company_name": "Anthropic" } } ``` ### Response ```json theme={null} { "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: ```yaml theme={null} # 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](/conductor/building/security-authentication#api-execution-access-control) for full configuration options. ## List Ensembles Get all available ensembles. ### Request ```http theme={null} GET /api/v1/ensembles Authorization: Bearer {token} ``` **Query Parameters**: * `tags` (string\[]) - Filter by tags * `search` (string) - Search by name/description ### Response ```json theme={null} { "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 ```http theme={null} GET /api/v1/ensembles/{name} Authorization: Bearer {token} ``` ### Response ```json theme={null} { "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 ```http theme={null} GET /api/v1/agents Authorization: Bearer {token} ``` ### Response ```json theme={null} { "agents": [ { "name": "company-enricher", "description": "Enrich company data", "inputs": {...}, "outputs": {...}, "operations": ["search", "scrape", "extract"] } ] } ``` ## Get Execution Status Get execution status and details. ### Request ```http theme={null} GET /api/v1/executions/{id} Authorization: Bearer {token} ``` ### Response ```json theme={null} { "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 ```http theme={null} POST /api/v1/executions/{id}/cancel Authorization: Bearer {token} ``` ### Response ```json theme={null} { "cancelled": true, "executionId": "exec-abc123..." } ``` ## List Executions Get execution history. ### Request ```http theme={null} 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 ```json theme={null} { "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 ```http theme={null} GET /api/v1/executions/{id}/state Authorization: Bearer {token} ``` ### Response ```json theme={null} { "state": { "counter": 5, "history": [...], "userPreferences": {...} }, "lastModified": 1705315200000 } ``` ## Update State Update ensemble state. ### Request ```http theme={null} PUT /api/v1/executions/{id}/state Content-Type: application/json Authorization: Bearer {token} { "state": { "counter": 6, "history": [...] } } ``` ### Response ```json theme={null} { "updated": true } ``` ## Get Logs Get execution logs. ### Request ```http theme={null} GET /api/v1/executions/{id}/logs Authorization: Bearer {token} ``` **Query Parameters**: * `level` (string) - Filter by log level * `agent` (string) - Filter by agent ### Response ```json theme={null} { "logs": [ { "timestamp": 1705315200000, "level": "info", "agent": "create-account", "message": "Creating user account", "metadata": {...} } ] } ``` ## Health Check Check API health. ### Request ```http theme={null} GET /api/v1/health ``` ### Response ```json theme={null} { "status": "healthy", "version": "1.0.0", "uptime": 123456, "timestamp": 1705315200000 } ``` ## Error Response Format All errors follow this format: ```json theme={null} { "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**: ```http theme={null} X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1705315200 ``` When rate limited (429): ```json theme={null} { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded", "retryAfter": 3600 } } ``` ## Pagination List endpoints support cursor-based pagination: ```http theme={null} GET /api/v1/executions?limit=100&cursor=cursor-xyz... ``` Response includes: ```json theme={null} { "items": [...], "hasMore": true, "nextCursor": "cursor-abc..." } ``` ## Next Steps API authentication Webhook integration Rate limit details TypeScript API