API reference overview
The Bookbag HTTP API: a Chatbase-compatible v1 surface (chat, conversations, leads, contacts) and a modern AI-SDK-style v2. Base URL, versions, conventions, and where to start.
View as MarkdownThe Bookbag API lets you build directly on the same engine that powers your agents — send messages, read conversations, manage contacts, and capture leads from your own backend. Everything is plain JSON over HTTPS and authenticated with an API key.
All endpoints are served under https://app.bookbag.ai. For example, the v2 chat endpoint is https://app.bookbag.ai/api/v2/agents/{agentId}/chat.
Two API surfaces
Bookbag exposes two versioned surfaces. They share the same API keys and the same agents — pick the one that fits your integration.
| Surface | Use it for | Style |
|---|---|---|
| API v1 | Chatbase-compatible integrations: contacts, custom attributes, the legacy chat stream, conversations, and leads. | Chatbase-shaped envelopes: { message, data, pages }. |
| API v2 | New integrations. Modern REST with an AI-SDK-style streaming format, cursor pagination, rate-limit headers, and machine-readable error codes. | Envelopes: { data } / { data, pagination } / { error }. |
In every endpoint the chatbot / agent id is the same thing — your agent's numeric id. v1 paths call it chatbotId (Chatbase parity); v2 paths call it agentId.
Conventions
- All requests use TLS. Send
Authorization: Bearer oc_...on every authenticated call. - Request and response bodies are JSON. Send
Content-Type: application/jsononPOST,PATCH, andPUT. - Timestamps in v1 contacts and all of v2 are Unix seconds. Internal dashboard reads use millisecond strings — the documented public fields use seconds.
- Every v2 response includes an
x-request-idheader. Include it when contacting support about a specific call.
A first request
The health check needs no authentication and is the quickest way to confirm connectivity:
curl https://app.bookbag.ai/api/v2/health