# Chat from your application

Create a session, send a user's message to a published agent, read the reply, keep the conversation going across calls, and fetch its history.

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.

Video: Your first API call (2:54), https://katonicdocsmedia.blob.core.windows.net/developers/chat-from-your-application/a5f7b0e263d4/index.html

  
**Step 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.

  
**Step 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.

  
**Step 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.

   ```bash
   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.

   ```bash
   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:

   ```json
   {
     "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.

   ```bash
   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?"}]}'
   ```

   ```text
   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:

```python

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:

```python

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.

## Related

- Chat and completions
- Sessions
- [Use an OpenAI client library](/developers/guides/use-an-openai-client-library)
- Authentication

Source: https://docs.katonic.ai/developers/guides/chat-from-your-application
