Conversation Service API

API reference for managing conversations and chat sessions

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.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Request Body:

Field	Type	Required	Description
title	string	Yes	Conversation title
is_archived	boolean	No	Whether the conversation is archived (default: false)

Response:

Field	Type	Description
id	string (UUID)	Conversation ID
title	string	Conversation title
is_archived	boolean	Archived status
created_at	string (datetime)	Creation timestamp
updated_at	string (datetime)	Last update timestamp

Create Chat Session

Create a new chat session for a conversation with a specific language model.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Request Body:

Field	Type	Required	Description
conversation_id	string (UUID)	Yes	ID of the conversation
model_id	string (UUID)	Yes	ID of the language model to use

Response:

Field	Type	Description
id	string (UUID)	Chat session ID
conversation_id	string (UUID)	Conversation ID
model_id	string (UUID)	Model ID
status	string	Session status (“active”, “completed”, etc.)
created_at	string (datetime)	Creation timestamp
updated_at	string (datetime)	Last update timestamp

Stream Chat

Send a message and receive a streaming response from the language model.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Request Body:

Field	Type	Required	Description
chat_session_id	string (UUID)	Yes	ID of the chat session
message	string	Yes	User 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.

Request

curl -X GET {{baseUrl}}/api/conversation/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/conversation/list

Query Parameters:

Parameter	Required	Description
org_id	Yes	Organization ID

Get Conversation with Sessions

Get details of a specific conversation including its chat sessions.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID
conversation_id	Yes	Conversation ID

Get Messages

Get messages from a conversation.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID
conversation_id	Yes	Conversation ID
limit	No	Maximum number of messages to return (default: 20)
offset	No	Number of messages to skip (default: 0)

Error Responses

Status Code	Description
400	Bad Request - Invalid input or validation error
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal 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