HTTP Endpoints

https://your-worker.workers.dev/api/v1

Authorization: Bearer {your-api-token}

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

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

{
  "id": "exec-abc123...",
  "status": "completed",
  "output": {
    "result": "success",
    "data": {...}
  },
  "duration": 1234,
  "timestamp": 1705315200000,
  "trace": {...}
}

# ensemble.yaml
name: internal-workflow
apiExecutable: false  # Prevents API execution

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"
    }
  }'

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

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

{
  "output": {
    "company_data": {...}
  },
  "duration": 567,
  "operations": [
    {
      "name": "search",
      "operation": "http",
      "duration": 234,
      "cached": false
    }
  ]
}

# agents/sensitive-operation.yaml
name: sensitive-operation
operation: code
handler: ./handler.ts
apiExecutable: false  # Prevents API execution

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

{
  "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 /api/v1/ensembles/{name}
Authorization: Bearer {token}

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "updated": true
}

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

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

GET /api/v1/health

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

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Missing required field: email",
    "details": {
      "field": "email",
      "expected": "string"
    }
  }
}

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705315200

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retryAfter": 3600
  }
}

GET /api/v1/executions?limit=100&cursor=cursor-xyz...

{
  "items": [...],
  "hasMore": true,
  "nextCursor": "cursor-abc..."
}