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

# Introduction

> Developer-first API for Human-Like Voice AI

Welcome to the Butter AI API reference. Our API is designed to be intuitive, allowing you to manage AI agents, telephony, and business knowledge with simple HTTP requests.

## Base URL

All API requests should be made to:

```bash theme={null}
https://api.getbutter.ai
```

## Core Concepts

The API is organized around several key resources:

* **Agents**: The brain of your application. Configure LLMs, voices, and personalities.
* **Phone Numbers**: Buy or import numbers from Twilio or SIP providers to route calls.
* **Calls**: Initiate outbound calls or track inbound call lifecycle events.
* **Knowledge Base**: Manage the documents (RAG) that your agents reference during calls.
* **Tools**: Define custom API endpoints that agents can call to perform actions.

## Response Format

All responses are returned in standard JSON format using a three-tier envelope system:

### Single Entity (GET by ID)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "agent_a1b2c3d4e5f6",
    "agent_name": "Sales Rep"
  }
}
```

### Paginated List (GET list)

```json theme={null}
{
  "success": true,
  "data": [
    { "id": "agent_a1b2c3d4e5f6", "agent_name": "Sales Rep" },
    { "id": "agent_b2c3d4e5f6a7", "agent_name": "Support Agent" }
  ],
  "pagination": {
    "next_cursor": "eyJpZ...",
    "has_more": true,
    "page_size": 20,
    "total_count": 100
  }
}
```

### Action Result (POST/PUT/DELETE)

```json theme={null}
{
  "success": true,
  "message": "Agent created successfully",
  "data": {
    "id": "agent_a1b2c3d4e5f6",
    "agent_name": "Sales Rep"
  }
}
```

## ID Format

All resource IDs follow a consistent format with a prefix and 12+ hexadecimal characters:

| Resource     | Prefix   | Example              |
| ------------ | -------- | -------------------- |
| Agent        | `agent_` | `agent_a1b2c3d4e5f6` |
| Call         | `call_`  | `call_b2c3d4e5f6a7`  |
| Phone Number | `phon_`  | `phon_c3d4e5f6a7b8`  |
| Tool         | `tool_`  | `tool_d4e5f6a7b8c9`  |
| Document     | `doc_`   | `doc_e5f6a7b8c9d0`   |
| Integration  | `intg_`  | `intg_f6a7b8c9d0e1`  |

## Rate Limiting

The Butter AI API enforces rate limits based on your subscription tier. If you exceed these limits, the API will return a `429 Too Many Requests` status code.

| Tier           | Rate Limit             |
| :------------- | :--------------------- |
| **Starter**    | 10 requests per second |
| **Pro**        | 50 requests per second |
| **Enterprise** | Custom                 |

<Tip>
  If you are planning a high-volume outbound campaign, please contact our support team to ensure your rate limits are increased accordingly.
</Tip>