Start a run
Queue a run of the orchestration and answer 202 at once with its run_id and where to follow it. Learn how it ends by polling its status, by following its stream, or by giving it a webhook_url to call. On SynapseOrch Cloud, a run started when the plan's runs at once are all busy waits its turn: the answer then carries queue_position. See the public API guide.
apiKeyAuthorizationBearer <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.
orch_id*stringThe orchestration's id.
application/json- body
A run's input, and where to be called back when it ends.
message?stringThe 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.
length <= 100000""session_id?|A conversation id stored with the run, which the runs list returns.
initial_state?Merged into the run's shared state before the first step, so steps read state.<key>. A key that starts with _ is refused with a 422. SynapseOrch Cloud only: a self-hosted install's /api/v2 ignores the field, so pass state through /api/v1 there.
webhook_url?|A URL to call when the run ends. On SynapseOrch Cloud it must be a public https address.
webhook_secret?|Signs the call, so your server can check it came from SynapseOrch.
The run is queued.
application/json- response
run_id?stringstatus?stringstream_url?stringstatus_url?stringcurl -X POST "https://api.synapseorch.com/api/v2/orchestrations/orch_01a10a0f2d4b6c8e0a1b3c5d7e9f1a2b/run" \ -H "Authorization: Bearer sk-syn-..." \ -H "Content-Type: application/json" \ -d '{ "message": "Do you ship within 30 days?" }'{ "run_id": "run_01a10a1553d57036bae3d17421a4ba16", "status": "queued", "stream_url": "/api/v2/orchestrations/runs/run_01a10a1553d57036bae3d17421a4ba16/stream", "status_url": "/api/v2/orchestrations/runs/run_01a10a1553d57036bae3d17421a4ba16/status"}