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

# Public API

> Access your agent's data programmatically with the Totebot Public API

The Public API lets you access your agent's conversations, analytics, customers, and more programmatically. All endpoints are authenticated with an API key and return JSON responses.

<Note>The Public API is available on **Basic**, **Pro**, and **Scale** plans.</Note>

<Card title="API Reference (Swagger)" icon="code" href="https://api.totebot.ai/api-docs">
  Browse the full API reference with request/response schemas and try endpoints directly.
</Card>

## Authentication

All API requests require a **Bearer token** in the `Authorization` header. The token is your agent's API key.

```bash theme={null}
curl -H "Authorization: Bearer tb_pk_your_api_key_here" \
  https://api.totebot.ai/v1/agent
```

### Generate an API Key

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings** → **Security** for your agent.
  </Step>

  <Step title="Generate Key">
    Click **Generate API Key**. Your key will be displayed once. Copy it immediately and store it securely.
  </Step>

  <Step title="Use the Key">
    Include the key as a Bearer token in the `Authorization` header of every API request.
  </Step>
</Steps>

<Warning>
  Treat your API key like a password. It provides full read access to your agent's data. If compromised, revoke it immediately from **Settings** → **Security** and generate a new one.
</Warning>

### Rate Limits

The API allows **60 requests per 60 seconds** per agent per IP address. If you exceed this limit, you'll receive a `429 Too Many Requests` response.

## Endpoints

### Agent

| Method | Endpoint    | Description                                   |
| ------ | ----------- | --------------------------------------------- |
| GET    | `/v1/agent` | Get agent info (name, model, training status) |

### Chat

| Method | Endpoint   | Description                                          |
| ------ | ---------- | ---------------------------------------------------- |
| POST   | `/v1/chat` | Send a message to the agent (streaming SSE response) |

The chat endpoint accepts a `message`, optional `conversationId` to continue an existing conversation, and optional `identity` object for user tracking. Responses are streamed as Server-Sent Events with types: `chunk`, `completed`, `tool_call`, `action_started`, `action_completed`, `error`.

### Conversations

| Method | Endpoint                                                         | Description                                  |
| ------ | ---------------------------------------------------------------- | -------------------------------------------- |
| GET    | `/v1/conversations`                                              | List conversations (paginated, with filters) |
| GET    | `/v1/conversations/:conversationId`                              | Get a single conversation with full data     |
| GET    | `/v1/conversations/:conversationId/messages`                     | List messages only (lighter payload)         |
| PATCH  | `/v1/conversations/:conversationId/messages/:messageId/feedback` | Submit feedback (POSITIVE or NEGATIVE)       |

**Filters for listing conversations:** `page`, `limit` (max 250), `startDate`, `endDate`, `source` (PREVIEW, EMBED, TELEGRAM, WHATSAPP, EMAIL), `sentiment` (POSITIVE, NEGATIVE, NEUTRAL), `product`, `purchased` (yes/no), `customerId`.

### Analytics

| Method | Endpoint                | Description                                                         |
| ------ | ----------------------- | ------------------------------------------------------------------- |
| GET    | `/v1/analytics`         | Chat opens, messages, unique users, cart adds, checkout initiations |
| GET    | `/v1/analytics/revenue` | Total revenue, order count, currency, daily breakdown               |

Both endpoints accept optional `from` and `to` query parameters (ISO 8601 dates) to filter by date range.

### Insights

| Method | Endpoint                 | Description                                                          |
| ------ | ------------------------ | -------------------------------------------------------------------- |
| GET    | `/v1/insights/sentiment` | Sentiment distribution (positive/negative/neutral counts and scores) |
| GET    | `/v1/insights/intents`   | Top 3 conversation intents sorted by score                           |
| GET    | `/v1/insights/products`  | Product mentions with sentiment and frequency                        |
| GET    | `/v1/insights/questions` | Top questions grouped by semantic similarity                         |

### Customers

| Method | Endpoint        | Description                                      |
| ------ | --------------- | ------------------------------------------------ |
| GET    | `/v1/customers` | List all customers who interacted with the agent |

Supports `sortBy` parameter: `a-z`, `z-a`, `oldest`, `newest`.

### Knowledge

| Method | Endpoint        | Description                                                       |
| ------ | --------------- | ----------------------------------------------------------------- |
| GET    | `/v1/knowledge` | List knowledge sources (documents, Q\&A, links, text) with status |

### Orders

| Method | Endpoint     | Description                              |
| ------ | ------------ | ---------------------------------------- |
| GET    | `/v1/orders` | Paginated orders attributed to the agent |

Supports `skip` (default 0) and `take` (1-250, default 20) query parameters.

### Leads

| Method | Endpoint    | Description                          |
| ------ | ----------- | ------------------------------------ |
| GET    | `/v1/leads` | List all leads captured by the agent |

### Emails

| Method | Endpoint     | Description                                   |
| ------ | ------------ | --------------------------------------------- |
| GET    | `/v1/emails` | List emails collected through the chat widget |

### Integrations

| Method | Endpoint           | Description                                            |
| ------ | ------------------ | ------------------------------------------------------ |
| GET    | `/v1/integrations` | List all active integrations (channels and e-commerce) |