API v2 overview

The modern Bookbag REST surface: AI-SDK-style chat and streaming, cursor pagination, rate-limit headers, request ids, and machine-readable error codes.

View as Markdown

API v2 is the recommended surface for new integrations. It is a clean REST API rooted at https://app.bookbag.ai/api/v2, authenticated with the same Bearer oc_... keys, and shaped for the modern streaming chat clients (AI SDK style).

What's different from v1

Envelopes — successful reads return { data } or { data, pagination }; errors return { error: { code, message } }.
Cursor pagination — list endpoints take limit (1–100, default 20) and an opaque cursor, and return pagination: { cursor, hasMore, total }.
Rate-limit headers — every response carries X-RateLimit-* headers; 100 requests / 10s per key.
Request ids — every response includes x-request-id.
Machine error codes — stable code values like RESOURCE_NOT_FOUND and VALIDATION_INVALID_BODY.
End-user identity — pass your own userId on chat to group a person's conversations.

Resources

Method	Path	Purpose
GET	/api/v2/health	Liveness check (no auth).
POST	/api/v2/agents/:agentId/chat	Send a message; stream or JSON reply.
GET	/api/v2/agents/:agentId/conversations	List conversations (paged).
GET	/api/v2/agents/:agentId/conversations/:conversationId	Get a conversation + messages (paged).
GET	/api/v2/agents/:agentId/conversations/:conversationId/messages	List messages in a conversation.
GET	/api/v2/agents/:agentId/users/:userId/conversations	List one end-user's conversations.
GET	/api/v2/agents/:agentId/conversations/export	Export all conversations with messages.
POST	/api/v2/agents/:agentId/conversations/:conversationId/retry	Re-run the last user turn.
POST	/api/v2/agents/:agentId/conversations/:conversationId/tool-result	Submit a client-side tool result.
PATCH	/api/v2/agents/:agentId/conversations/:conversationId/messages/:messageId/feedback	Set thumbs up/down feedback.

Identifiers

Message ids are returned as strings prefixed with msg_ (e.g. msg_789). Conversation ids are numeric strings. Conversation status is mapped to ongoing (bot), taken_over (escalated), or ended (resolved). Timestamps are Unix seconds.

Health check

curl https://app.bookbag.ai/api/v2/health

Streaming format

The text-delta / [DONE] SSE protocol and how to parse it.

Chat with an agent

Send messages, continue conversations, identify users.

List conversations

Cursor pagination, messages, exports, feedback, retry.

Custom attributes

Streaming