Send a chat message
Send a message to an agent and wait for its answer. An Orchestrator agent runs its orchestration and answers with its result. The turn belongs to the server, not the request: a caller that stops waiting leaves it running to the end, and its answer is saved to the session.
status is completed, or the turn stopped for a person: awaiting_approval for a tool call its Tool Policy wants confirmed — answer it with approve — or paused for an Orchestrator agent's Human step, answered through resume with its run_id. refused_calls lists the tool calls this turn did not run. See the Chat API for the failure codes.
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.
application/json- body
A message for an agent.
message*stringThe message. @[path] vault mentions are read in, as in Chat.
1 <= length <= 100000agent?|The agent's id, or its exact name in any case. Omitted, the workspace's first agent answers; an unknown agent is a 404.
session_id?|Carries a conversation on: send the session_id an earlier turn returned. Omitted, a new conversation starts. SynapseOrch Cloud makes every session id itself, so an id it did not make is a 404, and one that belongs to another agent is a 409.
images?array<string>Self-hosted only: base64 data-URI images for a model that can see them — PNG, JPEG, GIF or WebP, at most 5, each up to 5 MB and 20 MB in all. SynapseOrch Cloud refuses images with a 422.
The agent's answer, or the question it stopped on.
application/json- response
response?stringstatus?stringagent_id?stringagent_name?stringsession_id?stringrefused_calls?array<unknown>citations?array<unknown>unresolved_citations?array<unknown>curl -X POST "https://api.synapseorch.com/api/v1/chat" \ -H "Authorization: Bearer sk-syn-..." \ -H "Content-Type: application/json" \ -d '{ "message": "What is the weather in London right now?", "agent": "Research Agent", "session_id": "user-session-123" }'{ "response": "The current weather in London is 12°C and cloudy...", "status": "completed", "agent_id": "agent_1726412345678", "agent_name": "Research Agent", "session_id": "user-session-123", "refused_calls": [], "citations": [], "unresolved_citations": []}{ "response": "The agent wants to run **scrape_url** — it reaches systems outside this workspace. Allow it?", "status": "awaiting_approval", "pending_call": { "tool_name": "scrape_url", "tool_args": { "url": "https://example.com" }, "category": "open_world", "approval_id": "3f9a1c2b7d4e5f60" }, "agent_id": "agent_1726412345678", "agent_name": "Research Agent", "session_id": "user-session-123"}{ "response": "Review the draft and approve or reject it.", "status": "paused", "run_id": "run_orch_k3j9x2a_1734567890123", "agent_id": "agent_1726412345678", "agent_name": "Report Pipeline", "session_id": "user-session-123"}