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

# POST /ai-chat

> Send a conversation history and receive an AI-generated reply. Supports multi-turn chats with user, assistant, and system roles.

## Endpoint

```
POST https://api.bunny.build/api/v1/ai-chat
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

The AI Chat API accepts a conversation history as an array of messages and returns the model's reply along with token usage statistics. Each message carries a `role` (`user`, `assistant`, or `system`) and a `content` string, enabling full multi-turn conversations and system-level instructions.

## Use cases

* Add AI-powered chat to any application without managing model infrastructure
* Build customer support bots with custom system prompts
* Prototype conversational features quickly with a single POST request
* Create multi-turn dialogue flows where prior context shapes each reply

## Details

Messages are processed in order, so the conversation history must be complete each time you call the API. The `system` role is used to set behavior or persona for the model. Up to 50 messages are accepted per request, and each message content is limited to 10,000 characters. Token usage is returned in the `usage` field when available.

## Request body

| Field      | Type  | Required | Description                                        |
| ---------- | ----- | -------- | -------------------------------------------------- |
| `messages` | array | Yes      | Ordered list of conversation messages (1–50 items) |

### Message object

| Field     | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `role`    | string | Yes      | One of: `user`, `assistant`, `system` |
| `content` | string | Yes      | Message text (max 10,000 characters)  |

### Example

```json theme={null}
{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant that replies concisely." },
    { "role": "user", "content": "What is the capital of France?" }
  ]
}
```

## Response

### 200 OK

| Field                     | Type           | Description                                              |
| ------------------------- | -------------- | -------------------------------------------------------- |
| `reply`                   | string         | The model's generated response                           |
| `usage`                   | object or null | Token usage statistics, or `null` if unavailable         |
| `usage.prompt_tokens`     | number         | Tokens consumed by the input messages                    |
| `usage.completion_tokens` | number         | Tokens generated in the reply                            |
| `usage.total_tokens`      | number         | Sum of prompt and completion tokens                      |
| `usage.reasoning_tokens`  | number         | Tokens used for internal reasoning (0 if not applicable) |

**Example**

```json theme={null}
{
  "reply": "The capital of France is Paris.",
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 9,
    "total_tokens": 37,
    "reasoning_tokens": 0
  }
}
```

### 400 Bad Request

Returned when the `messages` field is missing, not an array, empty, exceeds 50 items, or contains an invalid role or oversized content.

```json theme={null}
{
  "error": "messages is required and must be an array"
}
```

```json theme={null}
{
  "error": "messages[0]: role must be user, assistant, or system"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

### 502 Bad Gateway

Returned when the upstream AI service is unavailable or returns an unexpected error.

```json theme={null}
{
  "error": "AI service responded with 503"
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/ai-chat \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is the capital of France?" }
    ]
  }'
```