# 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.

## Optional example checks

- [Compare deployment methods][public-lab-deployment-fit-get]. Check your declared channels, website access and required features against Quickchat AI setup options. This does not inspect your website or account.

- [Check a sample MCP connection][public-lab-mcp-connection-get]. Initialize and list tools on the Cloudflare documentation or Microsoft Learn endpoint only. No sign-in or tool execution is performed.

## 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)
- Creating tokens requires the **Business plan** or higher; on lower plans the option is disabled and the endpoint returns `402 Payment Required`

:::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](/docs/api-reference/chat) page 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`.

## Webhooks

Quickchat AI does **not** send outbound webhooks. There is no way to subscribe to an event and have us POST to your endpoint when a message arrives, a conversation is handed off, or a conversation closes.

The available alternatives serve different purposes:

- **[AI Actions](/docs/ai-agent/actions)** call your API during a conversation. API Actions offer **AI decides**, **Before first reply**, and **When metadata matches** modes. The automatic modes attempt a call once per conversation under their documented conditions; they are not subscriptions to every message or handoff. Use them for tasks such as recording a lead or notifying your system when required data is available.
- **[Google Sheets](/docs/ai-agent/google-sheets)** adds a row when its Action runs. It does not automatically record every message or handoff.
- **Polling the [Conversations API](/docs/api-reference/conversations)** retrieves stored conversations and their events, including messages and any recorded handoff markers. Follow pagination and the READ rate limit above. Polling introduces delay; comparing conversation state between polls can miss intermediate changes. Do not assume this provides an exhaustive history of every handoff or assignment transition.

API access requires the Business plan; see [Plans & limits](/docs/pricing-and-plans).

## 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 |

---

[public-lab-deployment-fit-get]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/deployment-fit/lab/get/?placement=docs-api-overview-deployment-fit-get-v1

[public-lab-mcp-connection-get]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/mcp-connection/lab/get/?placement=docs-api-overview-mcp-connection-get-v1
