Conversations
Manage conversation history and messages.
Conversations
Conversations track the history of interactions with your assistants. They are automatically created when using chat completions with a conversation_id, or you can create them manually for more control.
List Conversations
/v1/conversationsReturns a paginated list of conversations in your workspace.
Query Parameters
Prop
Type
Response
{
"data": [
{
"id": "conv_abc123",
"assistant_id": "asst_xyz789",
"title": "Product questions",
"source": "api",
"status": "active",
"user_id": "user_123",
"message_count": 12,
"total_input_tokens": 1500,
"total_output_tokens": 950,
"total_cost_cents": 0.45,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T11:45:00Z",
"last_message_at": "2024-01-15T11:45:00Z"
}
],
"has_more": true,
"next_cursor": "cursor_abc"
}Create Conversation
/v1/conversationsCreates a new conversation.
Request Body
Prop
Type
Get Conversation
/v1/conversations/:idRetrieves a conversation with its messages.
Query Parameters
Prop
Type
Update Conversation
/v1/conversations/:idUpdates a conversation's metadata.
Request Body
Prop
Type
Delete Conversation
/v1/conversations/:idSoft-deletes a conversation.
Search Conversations
/v1/conversations/searchSearch conversations with full-text search and advanced filters.
Query Parameters
Prop
Type
Plus all parameters from List Conversations.
Get Statistics
/v1/conversations/statsGet aggregated statistics for conversations.
Query Parameters
Prop
Type
Response
{
"data": {
"total_conversations": 1500,
"active_conversations": 1200,
"archived_conversations": 280,
"deleted_conversations": 20,
"total_messages": 45000,
"total_input_tokens": 2500000,
"total_output_tokens": 1800000,
"total_cost_cents": 850,
"conversations_by_source": {
"api": 800,
"widget": 500,
"playground": 200
},
"activity_by_day": [
{ "date": "2024-01-15", "conversations": 45, "messages": 320 }
]
}
}Bulk Actions
/v1/conversations/bulkArchive or delete multiple conversations at once.
Request Body
{
"action": "archive",
"conversation_ids": ["conv_1", "conv_2", "conv_3"]
}Response
{
"data": {
"action": "archive",
"updated": 3,
"failed": 0
}
}Export Conversation
/v1/conversations/:id/exportExport a single conversation with all messages and metadata.
Returns a JSON download with conversation data.
Export User Data (GDPR)
/v1/conversations/export/user/:userIdExport all conversations for a specific user (GDPR compliance).
Returns a JSON download with all conversation data.
Messages
List Messages
/v1/conversations/:id/messagesList messages in a conversation with pagination.
Append Message
/v1/conversations/:id/messagesAppend a message to a conversation.
Request Body
Prop
Type
Pin/Unpin Message
/v1/conversations/:id/messages/:messageIdPin or unpin a message. Pinned messages are preserved during compaction.
{
"is_pinned": true
}Compaction
Long conversations can be compacted to reduce token usage while preserving context.
Compact Conversation
/v1/conversations/:id/compactCompact a conversation using the specified strategy.
Request Body
Prop
Type
Response
{
"data": {
"conversation_id": "conv_abc123",
"messages_compacted": 25,
"tokens_before": 15000,
"tokens_after": 4500,
"tokens_saved": 10500,
"compression_ratio": 0.7,
"preview_only": false
}
}Preview Compaction
/v1/conversations/:id/compact/previewPreview compaction without making changes.
Get Context
/v1/conversations/:id/contextGet the compacted context ready for LLM input.
Query Parameters
Prop
Type
Get Summaries
/v1/conversations/:id/summariesList all summaries created for a conversation.
Compaction Strategies
| Strategy | Description |
|---|---|
sliding_window | Keep only the most recent N messages |
summarization | Summarize older messages while keeping recent ones |
hybrid | Combine sliding window with summarization |
none | Disable automatic compaction |
Pinned messages are always preserved during compaction, regardless of strategy.