Authentication

Bearer Token Authentication

All API v2 endpoints (except the health check) require a Bearer token in the Authorization header:

Authorization: Bearer <api-key>

Getting an API Key

Go to the Chatbase Dashboard
Go to Workspace settings → API keys
Click Create API Key
Copy and securely store the generated key

API keys grant full access to your workspace. Never expose them in client-side code, public repositories, or browser network requests.

API v2 requires a Chatbase Standard Plan or above. Requests from accounts on unsupported plans will be rejected.

Example Request

curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello!"}'

Rate Limiting

The API enforces a rate limit of 100 requests per 10-second sliding window, scoped per API key and IP address.

Rate Limit Headers

Every response includes rate limit headers so you can track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the window (100).
`X-RateLimit-Remaining`	Number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp in milliseconds when the current window resets.
`Retry-After`	Seconds to wait before retrying. Only present on `429` responses.

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 status code:

{
  "error": {
    "code": "RATE_LIMIT_TOO_MANY_REQUESTS",
    "message": "Too many requests, please try again later"
  }
}

Use the Retry-After header to determine how long to wait before retrying:

async function fetchWithRetry(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get("Retry-After"), 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRetry(url, options);
  }

  return response;
}

Request ID

Every response includes an x-request-id header containing a unique identifier for the request. When contacting support about an error, always include this value to help with debugging.

x-request-id: req_a1b2c3d4e5f6

Getting Started

Endpoints

Bearer Token Authentication

Getting an API Key

Example Request

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Request ID

​Bearer Token Authentication

​Getting an API Key

​Example Request

​Rate Limiting

​Rate Limit Headers

​Handling Rate Limits

​Request ID

Bearer Token Authentication

Getting an API Key

Example Request

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Request ID