REST API Reference

Base URL

All endpoints are prefixed with the configured base path:

{origin}/api

Authentication

All endpoints require a valid Supabase JWT in the Authorization header:

Authorization: Bearer <supabase-access-token>

Sessions

List sessions

Returns all sessions for the authenticated user, including their chats and messages.

GET /api/sessions

Response 200 OK

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "title": "My Session",
    "master_chat_index": 0,
    "created_at": "2026-03-23T10:00:00Z",
    "updated_at": "2026-03-23T10:30:00Z",
    "chats": [
      {
        "id": "uuid",
        "session_id": "uuid",
        "position": 0,
        "model_name": "GPT-4",
        "context_text": "",
        "title": "GPT-4 Chat",
        "created_at": "2026-03-23T10:00:00Z",
        "messages": [
          {
            "id": "uuid",
            "chat_id": "uuid",
            "position": 0,
            "role": "user",
            "content": "Hello",
            "created_at": "2026-03-23T10:01:00Z"
          }
        ]
      }
    ]
  }
]

Create session

POST /api/sessions
Content-Type: application/json

Request body

{ "title": "Compare Models" }

The title field is optional; defaults to "New Session".

Response 200 OK

{
  "id": "uuid",
  "user_id": "uuid",
  "title": "Compare Models",
  "master_chat_index": 0,
  "created_at": "2026-03-23T10:00:00Z",
  "updated_at": "2026-03-23T10:00:00Z"
}

Delete session

Deletes the session and all its chats and messages (cascade).

DELETE /api/sessions/{id}

Response 200 OK

{ "deleted": true }

Update master chat index

PATCH /api/sessions/{id}/master
Content-Type: application/json

Request body

{ "master_chat_index": 1 }

Response 200 OK — Returns the updated session object.

Chats

Add chat to session

POST /api/sessions/{session_id}/chats
Content-Type: application/json

Request body

{
  "model_name": "GPT-4",
  "title": "GPT-4 Chat",
  "context_text": "You are a helpful assistant."
}

Field	Type	Required	Description
`model_name`	string	Yes	Must match a registered model name
`title`	string	Yes	Display title for the chat tab
`context_text`	string	No	System prompt injected as first message

Response 200 OK — Returns ChatWithMessages (chat object flattened with messages array).

Remove chat from session

DELETE /api/sessions/{session_id}/chats/{position}

Response 200 OK

{ "deleted": true }

Query chat (non-streaming)

Sends a user message and returns the complete assistant response.

POST /api/chats/{chat_id}/query
Content-Type: application/json

Request body

{ "content": "What is quantum computing?" }

Response 200 OK — Returns ChatWithMessages with all messages including the new user and assistant messages.

Sync chat

Truncates messages after a given position and re-queries from that point.

POST /api/chats/{chat_id}/sync
Content-Type: application/json

Request body

{
  "msg_idx": 2,
  "content": "Actually, explain it differently"
}

Field	Type	Description
`msg_idx`	integer	Position after which to truncate messages
`content`	string	New user message to insert after truncation

Response 200 OK — Returns ChatWithMessages with the updated message history.

Import chat

Imports a chat with full message history into an existing session.

POST /api/sessions/{session_id}/chats/import
Content-Type: application/json

Request body

{
  "model_name": "GPT-4",
  "title": "Imported Chat",
  "context_text": "Optional system prompt",
  "messages": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Hi there!" }
  ]
}

Response 200 OK — Returns ChatWithMessages with the imported chat and all messages.

Models

List available models

Returns all models registered in the plugin registry.

GET /api/models

Response 200 OK

[
  { "name": "GPT-4", "provider": "openai", "model_id": "gpt-4" },
  { "name": "Mistral Large", "provider": "mistral", "model_id": "mistral-large-latest" },
  { "name": "llama3", "provider": "ollama", "model_id": "llama3:latest" }
]

Context Items

List context items

GET /api/context-items?offset=0&limit=50

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`limit`	integer	50	Maximum items to return

Response 200 OK

[
  {
    "id": "uuid",
    "title": "Medical Expert",
    "category": "medical",
    "tags": ["doctor", "expert"],
    "owner": "all",
    "content": "You are a medical expert...",
    "created_at": "2026-03-23T10:00:00Z"
  }
]

Create context item

POST /api/context-items
Content-Type: application/json

Request body

{
  "title": "Code Reviewer",
  "category": "development",
  "tags": ["code", "review"],
  "content": "You are an expert code reviewer..."
}

Field	Type	Required	Description
`title`	string	Yes	Display title
`category`	string	Yes	Category label
`tags`	string[]	No	Tag array
`content`	string	Yes	Context content (used for embedding generation)

Response 200 OK — Returns the created ContextItem.

Search context items (semantic)

GET /api/context-items/search?q=heart+disease&limit=10

Parameter	Type	Default	Description
`q`	string	(required)	Search query text
`limit`	integer	10	Maximum results

Response 200 OK

[
  {
    "id": "uuid",
    "title": "Cardiology Expert",
    "category": "medical",
    "tags": ["cardiology"],
    "owner": "all",
    "content": "You are a cardiologist...",
    "created_at": "2026-03-23T10:00:00Z",
    "similarity": 0.89
  }
]

Suggestions

Search query suggestions

GET /api/suggestions?q=transformers&limit=5

Parameter	Type	Default	Description
`q`	string	(required)	Search query text
`limit`	integer	5	Maximum results

Response 200 OK

[
  { "id": "uuid", "query": "How do transformer models work?", "similarity": 0.92 },
  { "id": "uuid", "query": "Explain attention mechanisms", "similarity": 0.87 }
]

Error responses

All endpoints return errors in a consistent format:

{ "error": "Description of what went wrong" }

Status	Meaning
`401 Unauthorized`	Missing or invalid JWT token
`404 Not Found`	Resource not found or not owned by the user
`400 Bad Request`	Invalid request body or model not available
`500 Internal Server Error`	Database or provider error