Skip to Content
API ReferenceConversations

Conversations API

Endpoints for managing conversations and messages.

Endpoints Overview

MethodEndpointDescription
GET/notebooks/:notebookId/conversationsList conversations
POST/notebooks/:notebookId/conversationsCreate a conversation
POST/conversations/:id/messagesSend a message
GET/conversations/:id/messagesList messages

List Conversations

GET /notebooks/:notebookId/conversations

Returns all conversations in a notebook.

Response

{ "data": [ { "id": "conv_123", "title": "Research Questions", "messageCount": 12, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:45:00Z" } ] }

Create Conversation

POST /notebooks/:notebookId/conversations

Creates a new conversation in a notebook.

Request Body

{ "title": "Research Questions" }

Response

{ "data": { "id": "conv_456", "title": "Research Questions", "createdAt": "2024-01-21T09:00:00Z" } }

Send Message

POST /conversations/:conversationId/messages

Sends a message and receives an AI response.

Request Body

{ "content": "What are the key findings from my sources?" }

Response

{ "data": { "id": "msg_123", "role": "assistant", "content": "Based on your sources, the key findings are...", "citations": [ { "sourceId": "src_456", "text": "...", "page": 12 } ], "creditsUsed": 2 } }

Streaming

For real-time responses, use streaming:

{ "content": "Summarize this document", "stream": true }
Tip

Use stream: true to receive responses as server-sent events for real-time display.


List Messages

GET /conversations/:conversationId/messages

Returns all messages in a conversation.

Query Parameters

ParameterTypeDescription
limitintegerMessages per page (default: 50)
beforestringCursor for pagination

Response

{ "data": [ { "id": "msg_001", "role": "user", "content": "What is the main topic?", "createdAt": "2024-01-15T10:30:00Z" }, { "id": "msg_002", "role": "assistant", "content": "The main topic is...", "citations": [...], "createdAt": "2024-01-15T10:30:05Z" } ] }

Credits

Each message consumes credits based on complexity:

Response TypeApproximate Cost
Short answer~1 credit
Detailed response~2-3 credits

Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid message content
402INSUFFICIENT_CREDITSNot enough credits
404NOT_FOUNDConversation not found

Learn More

Last updated on