Conversations API

Manage multi-turn conversations with AI models. Conversations support provider switching mid-session, SSE streaming, and usage tracking.

List Conversations

GET /api/v1/conversations

Returns all conversations for the authenticated user. Admin users see all conversations.

Response

{
  "items": [
    {
      "id": "conv_abc123",
      "model": "glm-5.1",
      "created_at": 1716192000000,
      "updated_at": 1716192100000
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Supports pagination via ?page=N&per_page=M query parameters.

Get Conversation Detail

GET /api/v1/conversations/:conv_id

Returns the conversation with all messages and metadata.

Response

{
  "id": "conv_abc123",
  "model": "glm-5.1",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Explain the OTP supervision tree",
      "created_at": 1716192000000,
      "meta": {}
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "The OTP supervision tree is a hierarchical process structure...",
      "created_at": 1716192001000,
      "meta": {"model": "glm-5.1", "tokens": 150}
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 150,
    "total_tokens": 195
  }
}

Error Responses

Code	Description
403	Not the conversation owner
404	Conversation not found

Create a Conversation

Conversations are created implicitly when sending the first message via the Anthropic-compatible Messages API or OpenAI-compatible Chat Completions API:

POST /api/v1/messages
POST /api/v1/chat/completions

See the API Overview for provider-specific endpoint details.

Stream Conversation Events

GET /api/v1/conversations/:conv_id/events

Subscribe to real-time events for a conversation via Server-Sent Events (SSE).

Response

Returns Content-Type: text/event-stream with heartbeat every 15 seconds:

event: heartbeat
data: {}

event: message
data: {"id": "msg_003", "role": "assistant", "content": "..."}

event: message
data: {"id": "msg_004", "role": "user", "content": "..."}

Error Responses

Code	Description
403	Not the conversation owner
404	Conversation not found

Delete a Conversation

DELETE /api/v1/conversations/:conv_id

Permanently delete a conversation and all its messages. Only the owner can delete.

Response

{
  "status": "ok"
}

Error Responses

Code	Description
403	Not the conversation owner
404	Conversation not found

Get a Single Message

GET /api/v1/messages/:message_id

Retrieve a specific message by its ID. Ownership is checked via the parent conversation.

Response

{
  "id": "msg_002",
  "role": "assistant",
  "content": "The OTP supervision tree is a hierarchical process structure...",
  "created_at": 1716192001000,
  "meta": {
    "model": "glm-5.1",
    "tokens": 150
  }
}

Error Responses

Code	Description
404	Message not found

Get Conversation Usage

GET /api/v1/conversations/:conv_id/usage

Returns token usage statistics for a conversation.

Response

{
  "usage": {
    "input_tokens": 450,
    "output_tokens": 1500,
    "total_tokens": 1950
  }
}

Provider Switching

Conversations support switching providers mid-conversation. The system performs bidirectional message transformation between Anthropic and OpenAI formats:

curl -X POST http://127.0.0.1:21434/api/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_abc123",
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Continue"}]
  }'

The system automatically transforms the conversation history from the previous provider's format to the new provider's format.

Ownership

Conversations are owned by the user who created them. The ownership check uses sol_identity:check_resource_owner/3 which verifies the authenticated user's UUID matches the conversation's owner UUID. Admin users can access all conversations.

Compatiblity Endpoints

The Messages and Chat Completions endpoints support conversation-scoped operations:

Endpoint	Provider Format	Description
POST /api/v1/messages	Anthropic	Send message, get response
POST /api/v1/chat/completions	OpenAI	Send message, get response

Both endpoints accept a conversation_id parameter to continue an existing conversation. When stream is true, responses are delivered via SSE with incremental token events.