Send a chat message

POST

/api/v2/chat

Queue an agent's turn and answer 202 at once with the conversation's session_id and where to follow the turn: its stream, or its status. The agent is resolved first, so an unknown one is a 404 before anything is queued. Carry the conversation on by sending the session_id back with the next message.

A webhook_url is called when the turn ends, with status completed and the answer, or failed with The agent encountered an error processing your request. — the model's own error is never sent as the answer. See the public API guide.

On a self-hosted install stream_url carries no ?after=: the stream starts from the conversation's first event.

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.

Request Body

application/json

body

A message for an agent, and where to be called back when the turn ends.

message*string

The message. @[path] vault mentions are read in, as in Chat.

Length1 <= length <= 100000

agent?|

The agent's id, or its exact name in any case. Omitted, the workspace's first agent answers; an unknown agent is a 404 before anything is queued.

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. SynapseOrch Cloud refuses images with a 422.

webhook_url?|

A URL to call when the turn ends, with status completed and the answer, or failed. On SynapseOrch Cloud it must be a public https address.

webhook_secret?|

Signs the call, so your server can check it came from SynapseOrch.

Response Body

The turn is queued.

application/json

response

session_id?string

status?string

stream_url?string

status_url?string

curl -X POST "https://api.synapseorch.com/api/v2/chat" \  -H "Authorization: Bearer sk-syn-..." \  -H "Content-Type: application/json" \  -d '{    "message": "What are your payment terms for a new account?",    "agent": "Order desk"  }'

{  "session_id": "chat_01a1205c3e8f7a2b9d4c6e1f0a3b5d7c",  "status": "queued",  "stream_url": "/api/v2/chat/chat_01a1205c3e8f7a2b9d4c6e1f0a3b5d7c/stream?after=1790249607455-0",  "status_url": "/api/v2/chat/chat_01a1205c3e8f7a2b9d4c6e1f0a3b5d7c/status"}