Orchestrations

Orchestrations coordinate multiple agents across multi-domain tasks. A coordinator agent analyzes incoming messages and delegates subtasks to specialized entity agents based on their role descriptions, then synthesizes the entity responses into a single reply.

Common Patterns

Create an orchestration, add entity agents with clear role descriptions, then use the streaming endpoint. The coordinator handles delegation. Keep entity role descriptions specific and non-overlapping so the coordinator can route cleanly.

CRUD

POST /api/orchestrations

Create an orchestration.

{ "name": "Team", "strategy": "supervisor" }

requests.post(f"{BASE_URL}/api/orchestrations", headers=headers, json={"name": "Team", "strategy": "supervisor"})

await fetch(`${BASE_URL}/api/orchestrations`, { method: "POST", headers, body: JSON.stringify({ name: "Team", strategy: "supervisor" }) });

curl -X POST '{BASE_URL}/api/orchestrations' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "Team"}'

GET /api/orchestrations

List all orchestrations.

requests.get(f"{BASE_URL}/api/orchestrations", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations`, { headers });

curl '{BASE_URL}/api/orchestrations' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/orchestrations/

Get orchestration with its entities.

string

required

Orchestration ID

requests.get(f"{BASE_URL}/api/orchestrations/{orch_id}", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}`, { headers });

curl '{BASE_URL}/api/orchestrations/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PUT /api/orchestrations/

Update orchestration config.

string

required

Orchestration ID

requests.put(f"{BASE_URL}/api/orchestrations/{orch_id}", headers=headers, json={"name": "Updated"})

await fetch(`${BASE_URL}/api/orchestrations/${orchId}`, { method: "PUT", headers, body: JSON.stringify({ name: "Updated" }) });

curl -X PUT '{BASE_URL}/api/orchestrations/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "Updated"}'

DELETE /api/orchestrations/

Delete an orchestration.

string

required

Orchestration ID

requests.delete(f"{BASE_URL}/api/orchestrations/{orch_id}", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/orchestrations/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Entities

POST /api/orchestrations//entities

Add an agent as an entity.

string

required

Orchestration ID

string

required

Use "agent". The route accepts any string ≤50 chars, but the orchestrator’s execution path only invokes entities where entity_type === "agent"; other values are stored but silently skipped at run time.

string

required

UUID of the agent to add.

string

Free-text role hint shown to the coordinator when delegating. Replaces the prior role field used in older docs examples.

object

Per-entity overrides; defaults to {}.

integer

Sort order in list responses; defaults to 0.

The route returns 400 if either entity_type or entity_ref_id is missing. List/PUT responses key off entity_ref_id and role_description, so any client trying to round-trip will see the same field names.

{
  "entity_type": "agent",
  "entity_ref_id": "agent-uuid",
  "role_description": "Handles billing"
}

requests.post(f"{BASE_URL}/api/orchestrations/{orch_id}/entities", headers=headers, json={"entity_type": "agent", "entity_ref_id": agent_id, "role_description": "Handles billing"})

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/entities`, { method: "POST", headers, body: JSON.stringify({ entity_type: "agent", entity_ref_id: agentId, role_description: "Handles billing" }) });

curl -X POST '{BASE_URL}/api/orchestrations/{id}/entities' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"entity_type": "agent", "entity_ref_id": "agent-uuid", "role_description": "Handles billing"}'

GET /api/orchestrations//entities

List entities in the orchestration.

string

required

Orchestration ID

requests.get(f"{BASE_URL}/api/orchestrations/{orch_id}/entities", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/entities`, { headers });

curl '{BASE_URL}/api/orchestrations/{id}/entities' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PUT /api/orchestrations//entities/

Update an entity. Only role_description, config, and position are writable; any other top-level keys are silently ignored. entity_type and entity_ref_id are not updatable; create a new entity instead.

string

required

Orchestration ID

string

required

Entity ID

string

Free-text role hint shown to the coordinator when delegating.

object

Per-entity overrides.

integer

Sort order in list responses.

{ "role_description": "Updated role" }

requests.put(f"{BASE_URL}/api/orchestrations/{orch_id}/entities/{entity_id}", headers=headers, json={"role_description": "Updated role"})

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/entities/${entityId}`, { method: "PUT", headers, body: JSON.stringify({ role_description: "Updated role" }) });

curl -X PUT '{BASE_URL}/api/orchestrations/{id}/entities/{eid}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"role_description": "Updated role"}'

DELETE /api/orchestrations//entities/

Remove an entity.

string

required

Orchestration ID

string

required

Entity ID

requests.delete(f"{BASE_URL}/api/orchestrations/{orch_id}/entities/{entity_id}", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/entities/${entityId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/orchestrations/{id}/entities/{eid}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Execution

POST /api/orchestrations//run/stream

Run orchestration with streaming SSE. Includes delegation events.

string

required

Orchestration ID

{ "message": "Hello" }

requests.post(f"{BASE_URL}/api/orchestrations/{orch_id}/run/stream", headers=headers, json={"message": "Hello"}, stream=True)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/run/stream`, { method: "POST", headers, body: JSON.stringify({ message: "Hello" }) });

curl -N -X POST '{BASE_URL}/api/orchestrations/{id}/run/stream' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"message": "Hello"}'

GET /api/orchestrations/runs/

Get orchestration run result.

string

required

Run ID

requests.get(f"{BASE_URL}/api/orchestrations/runs/{run_id}", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/runs/${runId}`, { headers });

curl '{BASE_URL}/api/orchestrations/runs/{run_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Hooks

These endpoints register hooks against an orchestration using the same ai.hooks model as agent hooks: event, type, config, matcher, enabled, and position.

Orchestration hooks are not executed yet. The CRUD endpoints below work (you can create, list, and delete hook rows), but the orchestration engine does not currently fire them at runtime, so a registered hook has no effect on an orchestration run today. Register them only for forward-compatibility. When execution lands, orchestration hooks will follow the agent hook contract (events such as OnRunStart/OnRunComplete, types http/rule/approval). The event and type you send are stored verbatim and not validated.Hooks attached to a member agent also do not fire while that agent runs inside an orchestration; only standalone agent runs execute hooks today. If you rely on an agent’s approval or policy hook, run that agent directly rather than as part of an orchestration until this lands.

POST /api/orchestrations//hooks

Add a hook.

string

required

Orchestration ID

string

required

Lifecycle event name. Stored verbatim; not validated.

string

required

Hook handler type: http, rule, or approval (see the agent hook contract).

object

required

Handler-specific configuration (for http, includes url).

string

Optional filter narrowing when the hook fires.

boolean

Defaults to true.

integer

Execution order within the event. Defaults to 0.

{
  "event": "OnRunComplete",
  "type": "http",
  "config": { "url": "https://example.com/orch-hook" },
  "enabled": true,
  "position": 0
}

requests.post(f"{BASE_URL}/api/orchestrations/{orch_id}/hooks", headers=headers, json={"event": "OnRunComplete", "type": "http", "config": {"url": "https://example.com/hook"}})

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/hooks`, { method: "POST", headers, body: JSON.stringify({ event: "OnRunComplete", type: "http", config: { url: "https://example.com/hook" } }) });

curl -X POST '{BASE_URL}/api/orchestrations/{id}/hooks' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"event": "OnRunComplete", "type": "http", "config": {"url": "..."}}'

GET /api/orchestrations//hooks

List hooks for the orchestration, ordered by position.

string

required

Orchestration ID

requests.get(f"{BASE_URL}/api/orchestrations/{orch_id}/hooks", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/hooks`, { headers });

curl '{BASE_URL}/api/orchestrations/{id}/hooks' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/orchestrations//hooks/

Remove a hook.

string

required

Orchestration ID

string

required

Hook ID

requests.delete(f"{BASE_URL}/api/orchestrations/{orch_id}/hooks/{hook_id}", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/hooks/${hookId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/orchestrations/{id}/hooks/{hook_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Sessions

Session-level reads on orchestrations. The streaming /run/stream endpoint returns a session_id you can use here to fetch history.

GET /api/orchestrations//sessions

List the most recent 100 sessions for an orchestration. Each entry includes session_id, run_count, first_message, last_activity_at, and created_at.

string

required

Orchestration ID

requests.get(f"{BASE_URL}/api/orchestrations/{orch_id}/sessions", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/sessions`, { headers });

curl '{BASE_URL}/api/orchestrations/{id}/sessions' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/orchestrations//sessions//messages

Assembled messages for a session. Each assistant message carries per-run reasoning replay metadata (reasoning_requested, reasoning_duration_ms, reasoning, events) so a chat UI can re-render the original “Thought for X.Xs” pill on refresh. Tool calls are attached per-message via tool_calls. The legacy top-level events field is preserved for older clients.

string

required

Orchestration ID

string

required

Session ID

requests.get(f"{BASE_URL}/api/orchestrations/{orch_id}/sessions/{session_id}/messages", headers=headers)

await fetch(`${BASE_URL}/api/orchestrations/${orchId}/sessions/${sessionId}/messages`, { headers });

curl '{BASE_URL}/api/orchestrations/{id}/sessions/{session_id}/messages' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Error Responses

Orchestration routes return {"error": "<message>"} (no structured error code field).

Status	Description
400	The orchestration has no entity agents; add at least one before running
400	Hook POST is missing one of `event`, `type`, or `config`
404	No orchestration exists with the given ID
404	No hook exists with the given ID for this orchestration
404	No orchestration session with the given ID

Getting Started

Concepts

Guides

API Reference

Common Patterns

CRUD

POST /api/orchestrations

GET /api/orchestrations

GET /api/orchestrations/

PUT /api/orchestrations/

DELETE /api/orchestrations/

Entities

POST /api/orchestrations//entities

GET /api/orchestrations//entities

PUT /api/orchestrations//entities/

DELETE /api/orchestrations//entities/

Execution

POST /api/orchestrations//run/stream

GET /api/orchestrations/runs/

Hooks

POST /api/orchestrations//hooks

GET /api/orchestrations//hooks

DELETE /api/orchestrations//hooks/

Sessions

GET /api/orchestrations//sessions

GET /api/orchestrations//sessions//messages

Error Responses

​Common Patterns

​CRUD

​POST /api/orchestrations

​GET /api/orchestrations

​GET /api/orchestrations/

​PUT /api/orchestrations/

​DELETE /api/orchestrations/

​Entities

​POST /api/orchestrations//entities

​GET /api/orchestrations//entities

​PUT /api/orchestrations//entities/

​DELETE /api/orchestrations//entities/

​Execution

​POST /api/orchestrations//run/stream

​GET /api/orchestrations/runs/

​Hooks

​POST /api/orchestrations//hooks

​GET /api/orchestrations//hooks

​DELETE /api/orchestrations//hooks/

​Sessions

​GET /api/orchestrations//sessions

​GET /api/orchestrations//sessions//messages

​Error Responses

Common Patterns

CRUD

POST /api/orchestrations

GET /api/orchestrations

GET /api/orchestrations/

PUT /api/orchestrations/

DELETE /api/orchestrations/

Entities

POST /api/orchestrations//entities

GET /api/orchestrations//entities

PUT /api/orchestrations//entities/

DELETE /api/orchestrations//entities/

Execution

POST /api/orchestrations//run/stream

GET /api/orchestrations/runs/

Hooks

POST /api/orchestrations//hooks

GET /api/orchestrations//hooks

DELETE /api/orchestrations//hooks/

Sessions

GET /api/orchestrations//sessions

GET /api/orchestrations//sessions//messages

Error Responses