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

# API Reference

> Complete API documentation for the Annie platform

## Overview

The Annie API is a RESTful API that allows you to programmatically manage your AI voice agents, organizations, and conversations.

## Base URL

```
https://api.helloannie.com/v1
```

## Authentication

The Annie API supports two authentication methods:

### API Keys

API Keys are long-lived tokens that can be generated from the Developer Portal. API keys are prefixed with `annie-sk-v1-` and should be included in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer annie-sk-v1-xxxxx" https://api.helloannie.com/v1/bots
```

### OAuth Tokens

OAuth tokens are short-lived access tokens generated using the OAuth 2.0 Client Credentials flow. These are ideal for server-to-server integrations.

**Token Endpoint:** `https://annie-external-api.us.auth0.com/oauth/token`

```bash theme={null}
curl -X POST https://annie-external-api.us.auth0.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "audience": "https://api.helloannie.com"
  }'
```

## Response Format

All API responses follow this structure:

```json theme={null}
{
  "success": true,
  "data": { },
  "message": "Optional message"
}
```

## Rate Limiting

The default rate limit is **60 requests per minute** per organization. When exceeded, the API responds with HTTP `429 Too Many Requests`.

Response headers include:

* `X-RateLimit-Limit`: Maximum requests allowed
* `X-RateLimit-Remaining`: Requests remaining in current window
* `X-RateLimit-Reset`: When the window resets (UTC epoch seconds)

## Explore the API

<CardGroup cols={2}>
  <Card title="Bots" icon="robot" href="/api-reference/bots">
    Create and manage AI voice agents
  </Card>

  <Card title="Organizations" icon="building" href="/api-reference/organizations">
    Manage business locations and settings
  </Card>

  <Card title="Templates" icon="copy" href="/api-reference/templates">
    Apply pre-built training configurations
  </Card>

  <Card title="Conversations" icon="comments" href="/api-reference/conversations">
    Access conversation history and messages
  </Card>
</CardGroup>