Chat from your application
Public API
The chat route runs a published agent the way the Work Room does, with its knowledge sources, tools and guardrails, and returns one JSON reply. Pair it with a session so a user's follow-up questions land in the same conversation.
Who can use it: anyone holding an API key with the Chat scope, which the sessions routes need as well. The tenant must be licensed for the public API.
Recorded on .
- Create a key with the Chat scope
On the Developer Hub's API keys tab, select Create Key, name the key, pick the Chat only preset and add Read agents. Copy the key; it is shown once.
- Find the agent and send the message
On the Reference tab, paste the key and send
GET /public/v1/agentsto read the published agent's id. Then send the chat request below from your terminal or your application. - Read the reply
The response carries
message.content.GET /public/v1/sessionslists the session, and the key's owner sees the conversation in the Work Room.
Prerequisites
- An API key with the Chat scope. See Authentication.
- A published agent, built in Studio.
GET /public/v1/agentslists the tenant's published agents with the Read agents scope, or use the namespace and slug shown when the agent was published to the API channel. With noagent_idat all, the tenant's default assistant answers. On the current build an agent created throughPOST /public/v1/agentsis saved but cannot answer a turn, a known defect in the runtime configuration it is created with; chat with agents built in Studio until it is fixed. - Your tenant host. Every call below goes to
https://<your tenant host>/public/v1.
Send a message and keep the thread
-
Create a session. The body of this route is in camel case, unlike the rest of the API. Keep the
idit returns.curl -X POST "https://<your tenant host>/public/v1/sessions" \-H "Authorization: Bearer kapi_..." \-H "Content-Type: application/json" \-d '{"agentId": "support-assistant", "title": "Refund question from the web form"}' -
Send the user's message. Pass the agent, the session and the message. The route answers only the latest user message in
messages; earlier turns are kept by the session, not by what you resend.curl -X POST "https://<your tenant host>/public/v1/chat" \-H "Authorization: Bearer kapi_..." \-H "Content-Type: application/json" \-d '{"agent_id": "support-assistant","session_id": "<session-id>","messages": [{"role": "user", "content": "What does our refund policy say about digital goods?"}]}'The reply is one JSON object:
{"message": {"role": "assistant", "content": "Digital goods can be refunded within 14 days if ..."},"session_id": "<session-id>","agent_id": "support-assistant"} -
Continue the conversation. Send the next message with the same
session_id. Each call is one turn and, withoutstream, returns when the agent has finished. -
Stream the reply when you want it as it is produced. Add
"stream": trueto the same body and the route answers with atext/event-stream. Each event is adata:line carrying a JSON object with atype; the text arrives inTEXT_MESSAGE_CONTENTevents asdelta, a failure arrives as aRUN_ERRORevent witherroranderror_code, and the stream ends withdata: [DONE]. Other event types describe the run's steps and can be skipped by a client that only wants the text.curl -N -X POST "https://<your tenant host>/public/v1/chat" \-H "Authorization: Bearer kapi_..." \-H "Content-Type: application/json" \-d '{"agent_id": "support-assistant", "session_id": "<session-id>", "stream": true,"messages": [{"role": "user", "content": "And for annual plans?"}]}'data: {"type":"RUN_STARTED","run_id":"...","thread_id":"..."}data: {"type":"TEXT_MESSAGE_CONTENT","message_id":"...","delta":"Annual plans "}data: {"type":"TEXT_MESSAGE_CONTENT","message_id":"...","delta":"can be refunded pro rata ..."}data: {"type":"RUN_FINISHED","run_id":"...","thread_id":"..."}data: [DONE]The registry-path form of the route, below, does not stream.
-
Read the history when you need it.
GET /public/v1/sessions/<session-id>/historyreturns the session's messages, oldest first, withhas_more; to read the earlier page, pass the first message'sidasbefore.
In Python, the whole exchange is a few lines:
import requests
BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}
session = requests.post(f"{BASE}/sessions", headers=HEADERS,
json={"agentId": "support-assistant", "title": "Web form"}).json()
def ask(text: str) -> str:
r = requests.post(f"{BASE}/chat", headers=HEADERS, json={
"agent_id": "support-assistant",
"session_id": session["id"],
"messages": [{"role": "user", "content": text}],
})
r.raise_for_status()
return r.json()["message"]["content"]
print(ask("What does our refund policy say about digital goods?"))
print(ask("And for annual plans?"))
To stream instead, send stream: True and read the event lines as they arrive:
import json
with requests.post(f"{BASE}/chat", headers=HEADERS, stream=True, json={
"agent_id": "support-assistant", "session_id": session["id"], "stream": True,
"messages": [{"role": "user", "content": "And for annual plans?"}],
}) as r:
r.raise_for_status()
for line in r.iter_lines():
if not line.startswith(b"data: "):
continue
payload = line[6:]
if payload == b"[DONE]":
break
event = json.loads(payload)
if event["type"] == "TEXT_MESSAGE_CONTENT":
print(event["delta"], end="", flush=True)
elif event["type"] == "RUN_ERROR":
raise RuntimeError(f"{event.get('error_code')}: {event.get('error')}")
Chat by registry path
An agent published to the API channel also answers at POST /public/v1/<namespace>/<slug>/chat, the address shown when it was published. The body is the same without agent_id. An agent that exists but is not published to that channel answers 404, the same as a missing agent.
Verify
The response carries message.content, and GET /public/v1/sessions/<session-id>/history lists your message and the reply. In the Work Room, the session's owner sees the conversation among their threads.
Troubleshooting
- 401 with
AUTH_ERROR: the key is missing, malformed or unknown. Fix the key rather than retrying. - 401 with
AUTH_ERRORandInvalid or expired API key, but the key works on other routes: the key lacks the Chat scope, which the gateway checks while validating the key. Create a key with the Chat only or Full access preset. - 404 with
Agent not foundon the registry path: the namespace or slug is wrong, or the agent is not published to the API channel. - 502 whose
detailis an error message: the agent's run failed and the route relays the run's own error. Try again; if it repeats, open the agent in Studio and run the same question on its Test tab. - A session is missing from the list: the list shows only sessions created by the key's owner, and only those with at least one message.
- 429 with
RATE_LIMITED: wait for the time inX-RateLimit-Reset; see API overview.