Skip to main content

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.

VideoYour first API call2:54

Recorded on .

  1. 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.

  2. Find the agent and send the message

    On the Reference tab, paste the key and send GET /public/v1/agents to read the published agent's id. Then send the chat request below from your terminal or your application.

  3. Read the reply

    The response carries message.content. GET /public/v1/sessions lists 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/agents lists 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 no agent_id at all, the tenant's default assistant answers. On the current build an agent created through POST /public/v1/agents is 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​

  1. Create a session. The body of this route is in camel case, unlike the rest of the API. Keep the id it 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"}'
  2. 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"
    }
  3. Continue the conversation. Send the next message with the same session_id. Each call is one turn and, without stream, returns when the agent has finished.

  4. Stream the reply when you want it as it is produced. Add "stream": true to the same body and the route answers with a text/event-stream. Each event is a data: line carrying a JSON object with a type; the text arrives in TEXT_MESSAGE_CONTENT events as delta, a failure arrives as a RUN_ERROR event with error and error_code, and the stream ends with data: [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.

  5. Read the history when you need it. GET /public/v1/sessions/<session-id>/history returns the session's messages, oldest first, with has_more; to read the earlier page, pass the first message's id as before.

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_ERROR and Invalid 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 found on the registry path: the namespace or slug is wrong, or the agent is not published to the API channel.
  • 502 whose detail is 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 in X-RateLimit-Reset; see API overview.

Describes the platform as of .

Was this page helpful?