# Overview

> REST API reference for the Quickchat AI platform — authentication, base URL, rate limits, pagination, and error handling.

Quickchat AI provides a REST API for programmatic access to your AI Agent's configuration, Knowledge Base, Conversations, AI Actions, and more.

## Authentication

All API endpoints use Bearer token authentication. Include your API token in the `Authorization` header of every request:

```
Authorization: Bearer <API_TOKEN>
```

Tokens are created in the [Quickchat Dashboard](https://app.quickchat.ai/) under **External Apps > API**. Each token is a JWT that contains your `scenario_id`, so no additional identifier header is needed.

- Token validity: **52 weeks** from creation
- Tokens can be **revoked** at any time from the Dashboard
- Each token is scoped to a single AI Agent (scenario)

:::note
The realtime Chat endpoint (`POST https://app.quickchat.ai/chat`) accepts the same Bearer token as the rest of this API, but it lives outside the `/v1/api/` base path and requires `scenario_id` in the request body. See the [Chat](#chat) section below for the full reference.
:::

### Token Scopes

API tokens are created with one of two scopes:

| Scope | Access Level | Description |
|-------|-------------|-------------|
| `read_all` | Read-only | Can read all resources but cannot create, update, or delete |
| `write_all` | Read + Write | Full access to all endpoints, including write operations |

- Tokens are assigned a scope when created in the Dashboard under **External Apps > API**
- `write_all` scope includes all `read_all` permissions automatically
- Using a `read_all` token on a write endpoint returns `403` with `"Insufficient token scope. Required: write_all"`

:::tip
Use `read_all` tokens for monitoring, analytics, and read-only integrations. Only use `write_all` tokens when your integration needs to create or modify resources.
:::

**Scope requirements by endpoint group:**

| Endpoint Group | Read Operations | Write Operations |
|----------------|----------------|-----------------|
| Chatbot Settings | `read_all` | `write_all` |
| Knowledge Base Settings | `read_all` | `write_all` |
| Articles | `read_all` | `write_all` |
| Article Language URLs | `read_all` | `write_all` |
| Tags | `read_all` | — |
| File Upload | — | `write_all` |
| Import External Content | — | `write_all` |
| Intercom Knowledge Base | `read_all` | `write_all` |
| Widget Configuration | `read_all` | `write_all` |
| Conversations | `read_all` | — |
| Conversation Metadata | `read_all` | `write_all` |
| Handoff Configuration | `read_all` | `write_all` |
| Conversation Rating | `read_all` | `write_all` |
| AI Actions | `read_all` | `write_all` |

## Base URL

| Endpoint Group | Base URL |
|----------------|----------|
| Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating | `https://app.quickchat.ai/v1/api/` |
| Conversations | `https://app.quickchat.ai/v1/api_core/` |
| Realtime Chat | `https://app.quickchat.ai/chat` |

## Rate Limits

Rate limits are applied per token, per endpoint.

| Tier | Limit | Applies To |
|------|-------|------------|
| READ | 120 requests/min | GET and list operations |
| WRITE | 60 requests/min | POST, PATCH, PUT, DELETE |
| HEAVY | 20 requests/min | File uploads, imports, scraping |

When a rate limit is exceeded, the API returns HTTP `429 Too Many Requests`.

## Pagination

List endpoints support pagination via query parameters:

| Parameter | Description |
|-----------|-------------|
| `limit` <br/> integer | Number of items per page |
| `offset` <br/> integer | Number of items to skip |

Paginated responses follow this structure:

```json
{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}
```

## Error Handling

All errors are returned as JSON in the following format:

```json
{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}
```

| Status | Code | Description |
|--------|------|-------------|
| 400 | `BAD_REQUEST` | Invalid input or missing required fields |
| 401 | `PERMISSION_DENIED` | Invalid, expired, or revoked token |
| 402 | `PAYMENT_REQUIRED` | Active subscription required |
| 403 | `PERMISSION_DENIED` | Token lacks the required scope for this operation |
| 404 | `NOT_FOUND` | Resource not found |
| 409 | `CONFLICT` | Conflicting operation (e.g., concurrent modification) |
| 422 | `VALIDATION_ERROR` | Request body failed schema validation |
| 429 | `TOO_MANY_REQUESTS` | Rate limit exceeded |
| 500 | `UNKNOWN` | Internal server error |
| 503 | `SERVICE_UNAVAILABLE` | Temporary unavailability |

---