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

# API Reference - Arbol Voice AI REST API

> Complete REST API reference for Arbol's voice AI platform. Authentication, endpoints, rate limits, and error codes. Create agents, manage contacts, and handle phone conversations programmatically.

## Base URL

Send all API requests to:

```
https://api.getarbol.com
```

## Authentication

Every request requires a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Get your API key from [app.getarbol.com](https://app.getarbol.com) under **Settings → API Keys**.

<Warning>
  **Keep your keys secret.** Never commit them to GitHub, paste them in Slack, or use them in client-side JavaScript. API keys give full access to your account.
</Warning>

## Request Format

All requests use JSON. Include `Content-Type: application/json` in your headers:

```bash theme={null}
curl -X POST https://api.getarbol.com/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent"}'
```

## Response Format

All responses return JSON. Success = `2xx` status code. List endpoints include pagination:

```json theme={null}
{
  "items": [...],
  "total": 42,
  "page": 1,
  "pageSize": 20
}
```

## Error Handling

When something goes wrong, you'll get an HTTP error code and a JSON error object:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
```

| Status Code | Description                                          |
| ----------- | ---------------------------------------------------- |
| `400`       | Bad Request - Invalid parameters or request body     |
| `401`       | Unauthorized - Missing or invalid API key            |
| `403`       | Forbidden - Insufficient permissions                 |
| `404`       | Not Found - Resource does not exist                  |
| `409`       | Conflict - Resource already exists or state conflict |
| `422`       | Unprocessable Entity - Validation error              |
| `429`       | Too Many Requests - Rate limit exceeded              |
| `500`       | Internal Server Error                                |

## Rate Limiting

We limit requests per organization to keep the API fast for everyone. Hit the limit and you'll get a `429` status code. Check these headers to see your limits:

* `X-RateLimit-Limit` - Maximum requests per window
* `X-RateLimit-Remaining` - Remaining requests in the current window
* `X-RateLimit-Reset` - Unix timestamp when the window resets

## Pagination

List endpoints support pagination with the following query parameters:

| Parameter  | Type    | Default | Description                        |
| ---------- | ------- | ------- | ---------------------------------- |
| `page`     | integer | `1`     | Page number                        |
| `pageSize` | integer | `20`    | Number of items per page (max 100) |

## ID Prefixes

Every resource ID starts with a prefix so you can tell what it is at a glance:

| Resource     | Prefix | Example         |
| ------------ | ------ | --------------- |
| Agent        | `agt_` | `agt_abc123...` |
| Contact      | `cnt_` | `cnt_def456...` |
| Conversation | `cnv_` | `cnv_ghi789...` |
| Campaign     | `cmp_` | `cmp_jkl012...` |
| Property     | `prp_` | `prp_mno345...` |
| Document     | `doc_` | `doc_pqr678...` |

## Need Help?

If you run into issues or need support, head to your [dashboard](https://app.getarbol.com) to create a support ticket. You can also email us directly at [david@getarbol.com](mailto:david@getarbol.com).