Run an orchestration as a stream

POST

/api/v1/orchestrations/{orch_id}/run/stream

Start an orchestration and receive every event as server-sent events: data: lines of JSON, with a : ping comment line after 10 seconds without one. The request body is the same as run. When the run pauses, the stream sends human_input_required, then done, and closes. The run belongs to the server, not the stream: to see how it ended, read it back. The event types are listed in the Orchestrations API.

Authorization

apiKey

headerAuthorizationBearer <token>

An API key, sk-syn- and 32 characters. On SynapseOrch Cloud an owner or admin makes it under Settings → Developer; on a self-hosted install, under Settings → API Keys.

Path Parameters

orch_id*string

The orchestration's id.

Request Body

application/json

body

A run's input.

message?string

The run's input. It is stored in shared state as user_input (and user_query); an Agent or LLM step with no prompt template uses it as its task.

Lengthlength <= 100000

Default""

session_id?|

SynapseOrch Cloud only: a conversation id stored with the run, which the runs list returns. A self-hosted install's /api/v1 refuses the field with a 422.

initial_state?

Merged into the run's shared state before the first step, so steps read state.<key>. A key that starts with _ is the engine's own and is refused with a 422.

Response Body

A stream of server-sent events.

response?stringtext/event-stream

curl -X POST "https://api.synapseorch.com/api/v1/orchestrations/orch_01a10a0f2d4b6c8e0a1b3c5d7e9f1a2b/run/stream" \  -H "Authorization: Bearer sk-syn-..." \  -H "Content-Type: application/json" \  -d '{    "message": "SynapseOrch platform"  }'

data: {"type": "orchestration_start", "run_id": "run_orch_k3j9x2a_1734567890123_4f2a9c", "orchestration_id": "orch_k3j9x2a"}data: {"type": "step_start", "orch_step_id": "step_research", "step_name": "Research", "step_type": "agent"}data: {"type": "step_complete", "orch_step_id": "step_research", "step_name": "Research", "duration_seconds": 12.4}data: {"type": "orchestration_complete", "run_id": "run_orch_k3j9x2a_1734567890123_4f2a9c", "status": "completed", "final_state": {"research": "..."}}data: {"type": "final", "response": "# SynapseOrch platform\n\nSynapseOrch is…", "data": {"step_history": ["..."], "shared_state": {"...": "..."}}}data: {"type": "done"}