Conversations API
Endpoints for managing conversations and messages.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
| GET | /notebooks/:notebookId/conversations | List conversations |
| POST | /notebooks/:notebookId/conversations | Create a conversation |
| POST | /conversations/:id/messages | Send a message |
| GET | /conversations/:id/messages | List messages |
List Conversations
GET /notebooks/:notebookId/conversationsReturns 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/conversationsCreates 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/messagesSends 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/messagesReturns all messages in a conversation.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Messages per page (default: 50) |
before | string | Cursor 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 Type | Approximate Cost |
|---|---|
| Short answer | ~1 credit |
| Detailed response | ~2-3 credits |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid message content |
| 402 | INSUFFICIENT_CREDITS | Not enough credits |
| 404 | NOT_FOUND | Conversation not found |
Learn More
Last updated on