> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chattler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Talk to any Chattler agent from your own code over a small REST API.

Every Chattler agent can be reached over HTTPS with an API key. A request through the API runs the same runtime as Telegram, WhatsApp or the chat page: the agent's system prompt, knowledge base, tools and dialog history all apply, and replies are paid for from the owner's balance in the same way.

## What the API does

<CardGroup cols={2}>
  <Card title="Chat" icon="message" href="/api-reference/public-api/send-a-message-to-the-agent-and-wait-for-the-reply">
    Send one user message and get the agent's reply, with token usage and the amount charged.
  </Card>

  <Card title="Stream" icon="bolt" href="/guides/streaming">
    Same request, but the reply arrives token by token as server-sent events.
  </Card>

  <Card title="Conversations" icon="comments" href="/guides/conversations">
    List the conversations your key has had and page through their messages.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    First reply in five minutes with curl, Python or Node.
  </Card>
</CardGroup>

## The basics

|                |                                                                   |
| -------------- | ----------------------------------------------------------------- |
| Base URL       | `https://api.chattler.ai`                                         |
| Path prefix    | `/v1`                                                             |
| Authentication | `Authorization: Bearer cht_live_<key_id>.<secret>`                |
| Format         | JSON in, JSON out; `text/event-stream` for the streaming endpoint |
| Errors         | One envelope: `{"error": {"code", "message", "request_id"}}`      |
| Rate limit     | 120 requests per 60 seconds per key                               |

A key belongs to exactly one agent. Its permission is either `read-only` (list conversations and read messages) or `full` (also chat).

## Endpoints

| Method | Path                                                             | Permission            |
| ------ | ---------------------------------------------------------------- | --------------------- |
| `POST` | `/v1/agents/{agent_id}/chat`                                     | `full`                |
| `POST` | `/v1/agents/{agent_id}/chat/stream`                              | `full`                |
| `GET`  | `/v1/agents/{agent_id}/conversations`                            | `read-only` or `full` |
| `GET`  | `/v1/agents/{agent_id}/conversations/{conversation_id}/messages` | `read-only` or `full` |

## How conversations work

You do not create conversations. Each chat request names an `external_user_id`, the stable id of the end user on your side. Every message from the same external user through the same key continues the same conversation; a different key, even for the same agent, has its own separate history. See [Conversations](/guides/conversations).

<Note>
  This release is text only: a message is a string, and attachments are not accepted. Every response carries an `X-Request-ID` header; quote it when you report a problem.
</Note>