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

# REST API Overview

> Programmatically manage chatbots, list sources, send chat messages, and receive webhook events using the InsiteChat REST API. Bearer-token auth, JSON over HTTPS.

The **InsiteChat REST API** lets you programmatically list chatbots, retrieve training sources, send chat messages, and subscribe to events — useful for embedding InsiteChat inside your own product, automating support workflows, or building custom dashboards on top of your chatbot data.

Webhooks deliver real-time events (lead captured, message received, conversation started, conversation escalated) to a URL of your choice — see [Webhooks](/api-reference/webhooks).

## Base URL

All API requests are made to:

```
https://backend.insitechat.ai/api/v1
```

## Authentication

Every request must include your API key as a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer ic_<your-api-key>
```

API keys are prefixed with `ic_` followed by a URL-safe random token. See [Authentication](/api-reference/authentication) for how to create, list, and revoke keys.

## Response Format

All responses are JSON.

**Successful list endpoints return a bare array:**

```json theme={null}
[
  {
    "id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "Support Bot",
    "slug": "support-bot",
    "provider": "gemini",
    "is_active": true,
    "created_at": "2026-03-15T10:30:00+00:00"
  }
]
```

**Single-object endpoints return the object directly** (no wrapping envelope).

**Error responses** use Django Ninja's default shape — a single `detail` field describing what went wrong:

```json theme={null}
{
  "detail": "API rate limit exceeded. Max 60 requests per minute."
}
```

There are no machine-readable `code` fields on errors today; branch on the HTTP status code instead.

## HTTP Status Codes

| Code  | Meaning                                                                                                  |
| ----- | -------------------------------------------------------------------------------------------------------- |
| `200` | Success                                                                                                  |
| `400` | Bad request (malformed body, missing required field, or hit account limit such as max 5 active API keys) |
| `401` | Unauthorized — missing, invalid, or revoked API key                                                      |
| `404` | Resource not found, or chatbot not owned by the API key's user                                           |
| `429` | Rate limit exceeded **or** plan message quota exhausted (the `detail` text distinguishes them)           |
| `500` | Server error                                                                                             |

## Rate Limits

Per API key: **60 requests per minute** (rolling 60-second window). When you exceed it, the API returns:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail": "API rate limit exceeded. Max 60 requests per minute."}
```

There is **no `Retry-After` header** today — back off on a fixed schedule (e.g. wait 60 seconds, then retry).

Separately, the `POST /v1/chatbots/{id}/chat` endpoint counts against your **plan's monthly message quota** (see [plans & pricing](/plans-and-pricing)). When the quota is exhausted, the same endpoint also returns `429`, but with a quota-specific `detail` message (e.g. `"Monthly message limit reached."`). Branch on the message text if you need to distinguish the two.

<Info>
  Need higher rate limits or quota? [Contact support](mailto:support@insitechat.ai).
</Info>

## How to Get an API Key

<Steps>
  <Step title="Log in">
    Sign in at [insitechat.ai](https://insitechat.ai).
  </Step>

  <Step title="Open the Developer page">
    Navigate to **Dashboard** → **Developer** → **API Keys**.
  </Step>

  <Step title="Create a key">
    Click **Create API Key**, give it a descriptive name (e.g. *Production Server*), and click **Generate**.
  </Step>

  <Step title="Copy and store it">
    The full key is shown **only once** at creation time. Copy it to a secure store; if you lose it, revoke it and create a new one.
  </Step>
</Steps>

<Warning>
  Each user account is limited to **5 active API keys**. Revoke unused keys before creating new ones if you hit the cap. Treat keys like passwords — never expose them in client-side JavaScript, mobile bundles, or public repos. Always call the API from your backend.
</Warning>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Chatbots" href="/api-reference/chatbots">
    List chatbots and retrieve a single chatbot's details.
  </Card>

  <Card title="Chat" href="/api-reference/chat">
    Send a message to a chatbot and receive an AI-generated reply.
  </Card>

  <Card title="Sources" href="/api-reference/sources">
    List the training sources on a chatbot.
  </Card>

  <Card title="Webhooks" href="/api-reference/webhooks">
    Configure outgoing webhooks to receive real-time events.
  </Card>
</CardGroup>