Skip to content

api-reference.md

Latest commit

 

History

History
341 lines (249 loc) · 4.93 KB

api-reference.md

File metadata and controls

341 lines (249 loc) · 4.93 KB

API Reference

Base URL: http://localhost:8000

Interactive docs: http://localhost:8000/docs (Swagger UI)

Chat

Send Message

POST /api/chat

Streams an AI response via Server-Sent Events.

Request Body:

{
  "conversation_id": "uuid (optional — omit to create new conversation)",
  "model": "qwen3.5:9b (optional — uses user default)",
  "message": "Hello!",
  "image": "base64-encoded image (optional)"
}

SSE Events:

Event Type Fields Description
title conversation_id, title AI-generated chat title (first message only)
thinking content Reasoning token from the model
content content Response token
done conversation_id, message_id, user_message_id, tokens_used, tokens_per_sec, thinking_duration Stream complete
error content Error message

Example SSE stream:

data: {"type": "title", "conversation_id": "abc-123", "title": "Python Snake Game"}
data: {"type": "thinking", "content": "Let me think about this..."}
data: {"type": "content", "content": "Here's how to"}
data: {"type": "content", "content": " build a snake game:"}
data: {"type": "done", "conversation_id": "abc-123", "message_id": "msg-456", "tokens_used": 150, "tokens_per_sec": 45.2}

Regenerate Response

POST /api/chat/regenerate

Deletes the last assistant message and re-streams a new response.

Request Body:

{
  "conversation_id": "uuid",
  "message_id": "uuid of assistant message to regenerate",
  "model": "optional — override model"
}

Conversations

List Conversations

GET /api/conversations

Response: 200

[
  {
    "id": "uuid",
    "title": "Snake Game Help",
    "model_name": "qwen3.5:9b",
    "message_count": 4,
    "created_at": "2026-03-06T10:00:00",
    "updated_at": "2026-03-06T10:05:00"
  }
]

Create Conversation

POST /api/conversations

Request Body:

{
  "title": "New Chat (optional)",
  "model_name": "optional",
  "system_prompt": "optional"
}

Response: 201 — returns ConversationResponse

Get Conversation Detail

GET /api/conversations/{conv_id}

Response: 200

{
  "id": "uuid",
  "title": "Snake Game Help",
  "model_name": "qwen3.5:9b",
  "system_prompt": null,
  "created_at": "2026-03-06T10:00:00",
  "updated_at": "2026-03-06T10:05:00",
  "messages": [
    {
      "id": "msg-uuid",
      "role": "user",
      "content": "Help me build a snake game",
      "thinking": null,
      "image_base64": null,
      "tokens_used": 0,
      "tokens_per_sec": 0,
      "thinking_duration": 0,
      "created_at": "2026-03-06T10:00:00"
    }
  ]
}

Update Conversation

PUT /api/conversations/{conv_id}

Request Body:

{
  "title": "New title (optional)",
  "system_prompt": "optional"
}

Response: 200 — returns ConversationResponse

Delete Conversation

DELETE /api/conversations/{conv_id}

Response: 204 No Content

Messages

Get Messages

GET /api/conversations/{conv_id}/messages

Response: 200 — returns MessageResponse[]

Update Message

PUT /api/conversations/{conv_id}/messages/{msg_id}

Request Body:

{
  "content": "Updated message text"
}

Response: 200 — returns MessageResponse

Delete Message (with Undo)

DELETE /api/conversations/{conv_id}/messages/{msg_id}

Deletes this message and everything after it. Creates a snapshot for undo.

Response: 200

{
  "snapshot_id": "uuid",
  "deleted_count": 3,
  "conversation_deleted": false
}

Restore Snapshot (Undo)

POST /api/conversations/restore/{snapshot_id}

Restores previously deleted messages.

Response: 200

{
  "conversation_id": "uuid",
  "restored_count": 3
}

Models

List Models

GET /api/models

Response: 200

[
  {
    "name": "qwen3.5:9b",
    "size": "5.5 GB",
    "modified_at": "2026-03-01T12:00:00"
  }
]

Pull Model

POST /api/models/pull

Request Body:

{
  "name": "llama3.2"
}

User

Get User Profile

GET /api/user

Response: 200

{
  "id": "default",
  "name": "User",
  "default_model": "qwen3.5:9b",
  "system_prompt": null
}

Update User Preferences

PUT /api/user

Request Body:

{
  "name": "optional",
  "default_model": "optional",
  "system_prompt": "optional"
}

Health

Health Check

GET /api/health

Response: 200

{
  "status": "healthy",
  "ollama": true,
  "database": true
}

Error Responses

All errors follow this format:

{
  "detail": "Conversation not found"
}
Status Code Meaning
400 Bad request
404 Resource not found
422 Validation error (Pydantic)
500 Internal server error