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.

Which key. CRUD, entity and hook routes require the project’s service role key. Four conversation routes also accept a signed-in user’s access token, scoped to that user’s own sessions and runs: POST /api/orchestrations/{id}/run/stream, GET /api/orchestrations/runs/{run_id}, GET /api/orchestrations/{id}/sessions and GET /api/orchestrations/{id}/sessions/{session_id}/messages. See Which key for which route.

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. Accepts runtime_knowledge_bases — the same query-scoped KB references as the agent streaming endpoint, with the same entry shape, validation, and 10-entry cap. The references flow to every sub-agent in the orchestration: each sub-agent’s knowledge_search tool merges them with its own attached KBs for this request only (a sub-agent with no attached KBs gains the tool for the run). One caveat differs per sub-agent: an entry’s max_context_tokens is honored only for sub-agents whose search tool resolves to exactly one KB. With an end user’s access token, the same run-body limits apply as for agent runs: runtime_knowledge_bases, knowledge_bases, context_handler_id and by-reference context_items answer 403, and a session_id must name an existing orchestration session of that user’s (omit it to start a new one). There is no route to create an orchestration session up front; the first run creates it and returns its id. See Rules for end-user runs.

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. An end user can read only runs in their own orchestration sessions; anything else answers 404.

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 (with an end user’s token, only that user’s own sessions). 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
401	Missing or invalid bearer token; an end-user token without a UUID `sub` or an `exp`
403	An end user’s token on a route that requires the service role key, or an end user’s run body sets a service-role-only field
404	No orchestration session with the given ID, or (with an end user’s token) the session isn’t that user’s

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