Chat Gateway API

Base URL

Use the externally advertised chat-gateway host. Published agent rows include publicUrl when CHAT_GATEWAY_PUBLIC_HOST is set on the conductor:

https://agents.example.com

All routes require:

Authorization: Bearer ao_<env>_<token>

The bearer is minted from the conductor publish API for one published profile. It is scoped to the URL tenant and agent slug, checked against allowed origins when Origin is present, and rate-limited per key.

Error Responses

Every route below can also return one of these shared errors:

Status	Body	When
`401`	`{ "error": "unauthorized" }`	Missing or invalid bearer, a key belonging to a different tenant, or a key that does not match the published agent
`403`	`{ "error": "origin_not_allowed" }`	`Origin` header present and not in the published agent’s allowlist
`429`	`{ "error": "rate_limited" }`	Per-key rate limit exceeded; a `Retry-After` header gives the retry delay in seconds
`503`	`{ "error": "endpoint_paused" }`	Endpoint paused from the dashboard
`400`	`{ "error": "invalid_body", "message": "..." }`	Malformed JSON body
`400`	`{ "error": "message_required" }`	`message` field missing or empty

Send a Chat Message

Runs one message against a published agent. The gateway creates a conversation when conversation_id is omitted, otherwise it reuses the existing conversation’s runtime session.

Field	Type	Required	Description
`message`	string	Yes	User message to send to the published agent
`conversation_id`	string	No	Existing `conv_...` conversation to continue
`metadata`	object	No	Free-form metadata; `end_user_id` is persisted when present

curl -X POST https://agents.example.com/v1/chat/acme/support-bot \
  -H 'Authorization: Bearer ao_prod_...' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize my latest ticket."}'

Successful synchronous responses include the durable conversation and public run ids:

{
  "conversation_id": "conv_abcd1234",
  "message": "Here is the summary...",
  "public_run_id": "prun_abcd1234"
}

If the run exceeds the published agent’s syncMaxDurationSeconds, the endpoint returns 504 with sync_timeout, conversation_id, and public_run_id. syncMaxDurationSeconds defaults to 60 and can be set between 1 and 270 when creating or updating a published agent through the conductor publish API. There is a second, rarer 504 path: if the underlying watcher’s event stream closes before a terminal event is observed, the gateway also returns 504 with sync_timeout, but the body carries only { "error": "sync_timeout", "message": "run did not finish synchronously" }, with no conversation_id or public_run_id. In both cases, use the run or stream endpoints below to resume.

Stream a Chat Message

Starts a run and streams public Server-Sent Events. The request body is the same as Send a Chat Message.

curl -N -X POST https://agents.example.com/v1/chat/acme/support-bot/stream \
  -H 'Authorization: Bearer ao_prod_...' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Draft a customer reply."}'

Events:

Event	Payload	Notes
`delta`	`{ "text": "..." }`	Assistant text chunk
`tool`	`{ "id": "...", "name": "...", "status": "running" }`	Only when the published agent enables `exposeToolEvents`
`tool`	`{ "id": "...", "status": "ok or error" }`	Only when `exposeToolEvents` is enabled
`done`	`{ "public_run_id", "conversation_id", "message" }`	Terminal success
`error`	`{ "code": "upstream", "message", "public_run_id" }`	Terminal failure

The gateway also sends : ping heartbeat comments about every 15 seconds.

Get a Public Run

Returns the terminal output for a public run, or 202 Accepted while it is still dispatching or running.

{
  "public_run_id": "prun_abcd1234",
  "conversation_id": "conv_abcd1234",
  "message": "Final answer",
  "status": "ok"
}

error runs return 502; lost runs return 410.

Resume a Public Run Stream

Subscribes to an in-flight public run when its watcher is still alive. If the run is already terminal, the gateway emits one reconstructed done or error event from stored conversation history.

Get a Conversation

Returns recent conversation messages for the published agent. Query params:

Query	Description
`limit`	Max messages to return; default `50`, capped at `200` (values above 200 are clamped, not rejected)
`include=errors`	Include stored error messages

{
  "conversation_id": "conv_abcd1234",
  "messages": [
    { "role": "user", "content": "Hello", "at": "2026-05-15T10:00:00Z" },
    { "role": "assistant", "content": "Hi", "public_run_id": "prun_abcd1234", "at": "2026-05-15T10:00:02Z" }
  ]
}

​Base URL

​Error Responses

​Send a Chat Message

​Stream a Chat Message

​Get a Public Run

​Resume a Public Run Stream

​Get a Conversation