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

# API Overview

> Everything you need to start building with the Avala API — authentication, request format, errors, rate limits, and pagination.

## Base URL

All API requests are made to the following base URL:

```
https://api.avala.ai/api/v1
```

All requests must be made over HTTPS. Requests over plain HTTP will be rejected.

## Authentication

Authenticate every request by including your API key in the `X-Avala-Api-Key` header:

```bash theme={null}
curl https://api.avala.ai/api/v1/agents \
  -H "X-Avala-Api-Key: avk_..."
```

API keys are created in [Mission Control](https://avala.ai). See the [Authentication](/docs/api-reference/authentication) page for full details on creating and managing keys.

## Request Format

The API accepts JSON-encoded request bodies. Set the `Content-Type` header for requests with a body:

| Header            | Value              |
| ----------------- | ------------------ |
| `X-Avala-Api-Key` | Your API key       |
| `Content-Type`    | `application/json` |

## Response Format

All responses return JSON. Successful responses use standard HTTP status codes (`200`, `201`, `204`).

**Single resource:**

```json theme={null}
{
  "id": "agt_abc123",
  "name": "Research Agent",
  "status": "active",
  "created_at": "2025-09-15T08:30:00Z"
}
```

**Paginated list:**

```json theme={null}
{
  "next": "https://api.avala.ai/api/v1/agents?cursor=abc123",
  "previous": null,
  "results": [
    {
      "id": "agt_abc123",
      "name": "Research Agent"
    }
  ]
}
```

## Pagination

List endpoints return paginated results using cursor-based pagination. The response includes:

| Field      | Type             | Description                                                               |
| ---------- | ---------------- | ------------------------------------------------------------------------- |
| `next`     | `string \| null` | URL for the next page of results, or `null` if this is the last page      |
| `previous` | `string \| null` | URL for the previous page of results, or `null` if this is the first page |
| `results`  | `array`          | Array of resource objects                                                 |

To paginate through results, follow the `next` URL until it returns `null`.

### Pagination Best Practices

* **Use `limit` to control page size.** Default is 100. Use smaller pages (10-25) for interactive UIs, larger pages (100) for batch processing.
* **Follow `next` URLs directly.** Don't construct pagination URLs manually. The `next` URL includes the correct cursor and any filters you applied.
* **Handle empty pages.** A page with an empty `results` array and `next: null` means you've reached the end.
* **Don't assume page sizes.** The last page may contain fewer items than `limit`.
* **Use the Python SDK** for automatic pagination: `client.datasets.list()` returns a `CursorPage` with `has_more` and `next_cursor` attributes.

```python theme={null}
# Paginate through all datasets
import requests

headers = {"X-Avala-Api-Key": "YOUR_API_KEY"}
url = "https://api.avala.ai/api/v1/datasets/?limit=50"

all_datasets = []
while url:
    response = requests.get(url, headers=headers)
    data = response.json()
    all_datasets.extend(data["results"])
    url = data["next"]  # None when no more pages

print(f"Total datasets: {len(all_datasets)}")
```

## Error Codes

When a request fails, the API returns an appropriate HTTP status code with a JSON error body:

```json theme={null}
{
  "detail": "A human-readable description of the error."
}
```

| Status Code | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `400`       | **Bad Request** — The request body is invalid or missing required fields. |
| `401`       | **Unauthorized** — API key is missing, invalid, or expired.               |
| `403`       | **Forbidden** — The API key does not have permission for this action.     |
| `404`       | **Not Found** — The requested resource does not exist.                    |
| `429`       | **Too Many Requests** — You have exceeded the rate limit.                 |
| `500`       | **Internal Server Error** — Something went wrong on our end.              |

See the [Error Codes](/docs/api-reference/errors) page for detailed descriptions and remediation steps.

## Rate Limits

The API enforces the following rate limits:

| Limit              | Value                   |
| ------------------ | ----------------------- |
| Standard requests  | 100 requests per minute |
| Burst              | 20 requests per second  |
| Inference          | 10 requests per minute  |
| Concurrent uploads | 10 simultaneous uploads |
| Concurrent exports | 5 simultaneous exports  |

When you exceed a rate limit, the API returns a `429` status code. Use the rate limit headers to manage your request volume:

| Header                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed in the current window |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the current window resets  |

## Interactive API Docs

Explore and test every endpoint directly in your browser with the interactive API documentation:

<Card title="" icon="flask" href="https://api.avala.ai/docs/api/">
  <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Interactive API Reference</p>
  <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Try endpoints, inspect request and response schemas, and generate code samples.</p>
</Card>