Skip to content

Character Chat Sessions API

Manage character chat sessions (conversations) for users. This layer handles session CRUD, metadata, export, and helpers for preparing context for /api/v1/chat/completions.

Tag in OpenAPI: character-chat-sessions

Base URL

/api/v1/chats

Note: - Conversation metadata endpoints (filters, ranking, analytics, tree view) are under /api/v1/chat/conversations and /api/v1/chat/analytics.

Auth + Rate Limits

  • Single-user: X-API-KEY: <key>
  • Multi-user: Authorization: Bearer <JWT>
  • Standard limits apply; a small per-chat throttle is used by the legacy /complete test endpoint.

Endpoints

  • Create session: POST /api/v1/chats/
  • Get session: GET /api/v1/chats/{chat_id}
  • Get context (for completions): GET /api/v1/chats/{chat_id}/context
  • List sessions: GET /api/v1/chats/
  • Update session: PUT /api/v1/chats/{chat_id}
  • Delete session (soft): DELETE /api/v1/chats/{chat_id}
  • Export session: GET /api/v1/chats/{chat_id}/export
  • Get chat settings: GET /api/v1/chats/{chat_id}/settings
  • Update chat settings: PUT /api/v1/chats/{chat_id}/settings
  • Prepare character completion payload: POST /api/v1/chats/{chat_id}/completions
  • Run character completion (optional persistence/stream): POST /api/v1/chats/{chat_id}/complete-v2
  • Preview prompt assembly and budgets: POST /api/v1/chats/{chat_id}/prompt-preview
  • Legacy rate-limit test: POST /api/v1/chats/{chat_id}/complete

Notes - Ownership is enforced; only the creator can access their sessions. - Use the Messages API to send/edit/delete/search messages in a session. - For LLM replies, call POST /api/v1/chat/completions with a conversation_id and optional character_id.

Character Chat Settings Fields (Selected)

PUT /api/v1/chats/{chat_id}/settings accepts a merged settings object. Selected keys:

  • chatPresetOverrideId (string|null): Chat-level prompt preset ID used when presetScope is "chat".
  • chatGenerationOverride (object|null): Canonical per-chat generation override block.
  • generationOverrides (object|null): Legacy alias accepted for backward compatibility.
  • presetScope ("chat" or "character"): Controls whether chat preset override or character preset is default.

chatGenerationOverride / generationOverrides object shape: - enabled (bool, optional): If false, chat-level generation override is disabled. - temperature (number 0.0-2.0, optional) - top_p (number 0.0-1.0, optional) - repetition_penalty (number 0.0-3.0, optional) - stop (array[string], optional) - updatedAt (ISO timestamp, optional)

Compatibility and precedence: - Server reads canonical chatGenerationOverride first. - If missing, server falls back to legacy generationOverrides. - If both are present, canonical wins.

Examples

Create a session 

curl -X POST "http://localhost:8000/api/v1/chats/" \
  -H "Content-Type: application/json" -H "X-API-KEY: $API_KEY" \
  -d '{"character_id": 42, "title": "Mentor chat"}'

Get chat context for completions 

curl -X GET "http://localhost:8000/api/v1/chats/{chat_id}/context" \
  -H "X-API-KEY: $API_KEY"

Export as Markdown 

curl -X GET "http://localhost:8000/api/v1/chats/{chat_id}/export?format=markdown" \
  -H "X-API-KEY: $API_KEY"

List sessions (paginated) 

curl -X GET "http://localhost:8000/api/v1/chats/?page=1&per_page=20" \
  -H "X-API-KEY: $API_KEY"

Example list response 

{
  "success": true,
  "data": [
    {"id": "3f6c...", "character_id": 42, "title": "Mentor chat", "message_count": 5}
  ],
  "metadata": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1}
}