Skip to main content

​
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

  1. Go to the Chatbase Dashboard
  2. Navigate to Workspace Settings → API Keys
  3. Click Create API Key
  4. 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 paid Chatbase plan. Requests from free-plan accounts 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:
HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the window (100).
X-RateLimit-RemainingNumber of requests remaining in the current window.
X-RateLimit-ResetUnix timestamp in milliseconds when the current window resets.
Retry-AfterSeconds 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