The Conversation Service provides endpoints for creating and managing conversations, chat sessions, and handling message interactions with language models.

​
Authentication

All endpoints require a valid Bearer token in the Authorization header.

​
Base URL

/api/conversation

​
Endpoints

​
Create Conversation

Create a new conversation. 
curl -X POST {{baseUrl}}/api/conversation/create?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Discussion",
    "is_archived": false
  }'
Endpoint: POST /api/conversation/create Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
titlestringYesConversation title
is_archivedbooleanNoWhether the conversation is archived (default: false)
Response:
FieldTypeDescription
idstring (UUID)Conversation ID
titlestringConversation title
is_archivedbooleanArchived status
created_atstring (datetime)Creation timestamp
updated_atstring (datetime)Last update timestamp

​
Create Chat Session

Create a new chat session for a conversation with a specific language model. 
curl -X POST {{baseUrl}}/api/conversation/create_session?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
    "model_id": "457d4f38-e3c0-43eb-b519-a867f9f5325a"
  }'
Endpoint: POST /api/conversation/create_session Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
conversation_idstring (UUID)YesID of the conversation
model_idstring (UUID)YesID of the language model to use
Response:
FieldTypeDescription
idstring (UUID)Chat session ID
conversation_idstring (UUID)Conversation ID
model_idstring (UUID)Model ID
statusstringSession status (“active”, “completed”, etc.)
created_atstring (datetime)Creation timestamp
updated_atstring (datetime)Last update timestamp

​
Stream Chat

Send a message and receive a streaming response from the language model. 
curl -X POST {{baseUrl}}/api/conversation/stream_chat?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_session_id": "9b8c7d6e-5f4e-3d2c-1b0a-9z8y7x6w5v4u",
    "message": "Can you explain how vector databases work?"
  }'
Endpoint: POST /api/conversation/stream_chat Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
chat_session_idstring (UUID)YesID of the chat session
messagestringYesUser message to send to the language model
Response: Server-sent events (SSE) stream with the following event types:
  • start: Indicates the beginning of the response with a message ID
  • content: Contains chunks of the model’s response content
  • end: Indicates the end of the response

​
List Conversations

Get a list of all conversations for an organization. 
curl -X GET {{baseUrl}}/api/conversation/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/conversation/list Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID

​
Get Conversation with Sessions

Get details of a specific conversation including its chat sessions. 
curl -X GET {{baseUrl}}/api/conversation/get_with_sessions?org_id=your-org-id&conversation_id=your-conversation-id \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/conversation/get_with_sessions Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
conversation_idYesConversation ID

​
Get Messages

Get messages from a conversation. 
curl -X GET "{{baseUrl}}/api/conversation/messages?org_id=your-org-id&conversation_id=your-conversation-id&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/conversation/messages Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
conversation_idYesConversation ID
limitNoMaximum number of messages to return (default: 20)
offsetNoNumber of messages to skip (default: 0)

​
Error Responses

Status CodeDescription
400Bad Request - Invalid input or validation error
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side error

​
Implementation Notes

  • The streaming API uses Server-Sent Events (SSE) to deliver model responses
  • Messages are stored in the database and can be retrieved historically
  • Multiple chat sessions can be created for a single conversation, each using a different model
  • Responses are generated asynchronously, allowing for real-time streaming of content