# Overview

This section documents every endpoint in the CollieAI API.

## Base URL

```
https://api.collieai.com
```

If you are self-hosting, replace this with your own deployment URL.

## Authentication

CollieAI uses two authentication methods depending on the endpoint:

| Endpoint prefix | Auth method            | Description                                                                           |
| --------------- | ---------------------- | ------------------------------------------------------------------------------------- |
| `/v1/...`       | API key (Bearer token) | Used by your application to proxy LLM requests and manage resources programmatically. |
| `/api/v1/...`   | Session cookie         | Used by the CollieAI dashboard. Requires a logged-in session.                         |

### API Key Authentication

Pass your CollieAI API key in the `Authorization` header:

```
Authorization: Bearer clai_your_api_key_here
```

API keys are prefixed with `clai_` and scoped to a single project. See [API Keys](broken://pages/605639aeb31c3823e4c2f5364dd73989008ee8d5) for details.

### Session Authentication

Session cookies are set automatically when you sign in to the dashboard. No manual header is needed for browser-based requests.

## Error Format

All errors follow an OpenAI-compatible shape:

```json
{
  "error": {
    "message": "A human-readable description of what went wrong.",
    "type": "error_type",
    "code": 400
  }
}
```

### Common Error Types

| Type                    | Code | Description                                                      |
| ----------------------- | ---- | ---------------------------------------------------------------- |
| `invalid_request_error` | 400  | The request body is malformed or missing required fields.        |
| `policy_violation`      | 400  | A security rule with a **block** decision matched the content.   |
| `authentication_error`  | 401  | Missing, invalid, or expired API key or session.                 |
| `forbidden_error`       | 403  | The authenticated user does not have permission for this action. |
| `not_found_error`       | 404  | The requested resource does not exist.                           |
| `validation_error`      | 422  | One or more fields failed validation.                            |
| `rate_limit_exceeded`   | 429  | Too many requests. Back off and retry.                           |
| `provider_error`        | 502  | The upstream LLM provider returned an error.                     |
| `internal_error`        | 500  | An unexpected server error occurred.                             |

## Rate Limiting

API requests are subject to two types of rate limits:

* **Per-project burst limit (RPM):** Configurable requests-per-minute limit for each project. Returns `429` with `type: "rate_limit_exceeded"`.
* **Monthly usage limit:** Based on your subscription plan (Free: 15,000 calls/month, Growth: 2,000,000). Returns `429` with `type: "billing_limit"` when exceeded.

The `Retry-After` header indicates how many seconds to wait before retrying. Monthly usage includes a [grace buffer](broken://pages/1bc2faea1a669a7ca8ed2292f75af759eb0a317a) -- requests are blocked at 110% of the limit, not exactly 100%.

## Pagination

List endpoints support pagination with two query parameters:

| Parameter   | Default | Description                             |
| ----------- | ------- | --------------------------------------- |
| `page`      | 1       | The page number (1-indexed).            |
| `page_size` | 20      | Number of items per page (maximum 100). |

Paginated responses include metadata:

```json
{
  "items": [],
  "total": 42,
  "page": 1,
  "page_size": 20
}
```

## Endpoints

### Proxy

* [Chat Completions](broken://pages/e40b31afec2b513b89c48cbc802c29d89edebda8) -- OpenAI-compatible chat completions endpoint.

### Async

* [Jobs](broken://pages/0e6b7f91c15d5652725c55b3ea6c6ae8561491ed) -- Create and manage async processing jobs.

### Resources

* [Projects](broken://pages/2dd3d1f1292b4c8b64751c2318124e84573b4ff1) -- Create and manage projects.
* [Policies](broken://pages/974071e43e34df396cf3a19a4831e9e02222ff9b) -- Create and manage policies within a project.
* [Rules](broken://pages/00b5637d96dfd265be895ee331044894a7a072c0) -- Add, update, and remove rules from policies.
* [API Keys](broken://pages/6cb13479ca047ed1e97c429cf7614a04956550ba) -- Generate and manage API keys for a project.
* [Provider Tokens](broken://pages/b236bd5d0cc0f85211158563cc7ec12ac2be83e8) -- Store and manage LLM provider credentials.
* [Dictionaries](broken://pages/ea53fdc007e0db67b89d71b0cbf42f84b30a6d20) -- Upload and manage term dictionaries for matching rules.
* [Alerts](broken://pages/f4906ecb0d7ca9e59c7033effaade869c7fa8e3b) -- Configure and manage monitoring alerts.

### Account

* [Auth](broken://pages/5c1d14d1a46decf65385a9e9c839035ead448158) -- Sign in, sign out, and manage sessions.
* [Health](broken://pages/a8688ec77f9fd065d0171cb74a10edfad90797fd) -- Server health check.
* [Admin](broken://pages/5354f9aefdb7e60db3c3086ec0829df81d12b7f7) -- Administrative operations (user management, system resources).
* [Billing](broken://pages/a564693166e3d3009a084323287a273c793c619c) -- Subscription management, usage info, Stripe checkout and portal.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.collieai.io/api-reference/overview-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.