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.

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; 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`
`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" }
  ]
}

Operations

The gateway requires the same Postgres cluster as the conductor, Redis, the published-agent API key pepper, and a private conductor URL:

Variable	Description
`PORT`	Public listen port; defaults to `8090`
`CONDUCTOR_INTERNAL_URL`	Private conductor internal listener URL; `*.railway.app` public URLs are rejected
`POSTGRES_URL` / `POSTGRES_DSN` / `PG*`	Shared Postgres DSN using a non-superuser `NOBYPASSRLS` application role
`REDIS_URL`	Nonce replay and rate-limit backing store
`CHAT_GATEWAY_SIGNING_KEY_CURRENT`	Base64 HMAC key used to sign internal conductor requests
`CHAT_GATEWAY_SIGNING_KEY_PREVIOUS`	Optional previous signing key during rotation
`AGENT_API_KEY_PEPPER`	Base64 HMAC pepper used to hash public API keys
`CHAT_GATEWAY_PUBLIC_HOST`	Host used by conductor publish responses to derive `publicUrl`
`GATEWAY_RATE_LIMIT_BACKEND`	`redis` or `memory`; defaults to `redis`
`GATEWAY_SHUTDOWN_GRACE`	Graceful shutdown timeout; defaults to `25s`

The gateway refuses to start when the Postgres role is a SUPERUSER or has BYPASSRLS, because published_agents and gateway_runs reads are tenant-scoped by RLS. Use the same application-role pattern as the conductor. Health endpoints:

Method	Path	Description
`GET`	`/healthz`	Process liveness
`GET`	`/readyz`	Readiness for serving public chat traffic

​Base URL

​Send a Chat Message

​Stream a Chat Message

​Get a Public Run

​Resume a Public Run Stream

​Get a Conversation

​Operations