Overview

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 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 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 integer	Number of items per page
offset integer	Number of items to skip

Paginated responses follow this structure:

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

Error Handling

All errors are returned as JSON in the following format:

{
  "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

---