API Reference¶

This page provides detailed API documentation for the Agent chat system endpoints. All endpoints require authentication via a session.

Authentication¶

All API endpoints require authentication. Include a valid session cookie (sessionid) with your requests. This is automatically handled when using the web interface.

Threads¶

Thread management endpoints for creating, retrieving, listing, and deleting chat conversations.

Create Thread¶

POST /api/threads/create

Create Thread

Creates a new thread for chat conversations. Returns a unique thread ID that can be used for subsequent message operations.

Responses

201 Thread created successfully

{
  "thread_id": "550e8400-e29b-41d4-a716-446655440000"
}

401 Authentication required

{
  "error": "string"
}

500 Internal server error

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)

Get Thread Details¶

POST /api/threads/

Get Thread Details

Returns the details of a specific thread including its complete message history.

Request Body required

{
  "thread_id": "550e8400-e29b-41d4-a716-446655440000"
}

Responses

200 Thread details retrieved successfully

{
  "messages": [
    {
      "role": "user",
      "content": "string",
      "metadata": {}
    }
  ]
}

400 Bad request - missing or invalid parameters

{
  "error": "string"
}

401 Authentication required

{
  "error": "string"
}

404 Resource not found

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)

Delete Thread¶

DELETE /api/threads/

Delete Thread

Deletes a specific thread and all its associated messages.

Request Body required

{
  "thread_id": "550e8400-e29b-41d4-a716-446655440000"
}

Responses

200 Thread deleted successfully

{
  "success": true,
  "message": "Thread deleted successfully"
}

400 Bad request - missing or invalid parameters

{
  "error": "string"
}

401 Authentication required

{
  "error": "string"
}

404 Resource not found

{
  "error": "string"
}

500 Internal server error

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)

List Threads¶

POST /api/threads/list

List Threads

Returns a list of all threads for the authenticated user. Each thread includes its ID and a title derived from the first user message.

Responses

200 Threads retrieved successfully

{
  "memories": [
    {
      "id": "string",
      "title": "string"
    }
  ]
}

401 Authentication required

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)

Chat¶

Endpoint for processing chat messages with streaming responses.

Process Chat Message¶

POST /api/threads/runs

Process Chat Message

Processes a chat message for a specific thread and streams the AI response. Uses Server-Sent Events (SSE) for real-time token streaming.

Request Body required

{
  "message": "Hello, can you help me with a question?",
  "thread_id": "550e8400-e29b-41d4-a716-446655440000",
  "model_id": "123e4567-e89b-12d3-a456-426614174000"
}

Responses

200 Streaming response with AI-generated tokens

400 Bad request - missing or invalid parameters

{
  "error": "string"
}

401 Authentication required

{
  "error": "string"
}

403 Permission denied

{
  "error": "string"
}

404 Resource not found

{
  "error": "string"
}

500 Internal server error

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)

Files¶

File upload endpoint for attaching documents and images to chat threads.

Upload File¶

POST /api/files/upload

Upload File

Uploads a file and attaches it to a specific thread. The file is processed by the AI agent and a streaming response is returned.

Request Body required

Responses

200 File uploaded and processed successfully. Returns streaming response.

400 Bad request - missing or invalid parameters

{
  "error": "string"
}

401 Authentication required

{
  "error": "string"
}

404 Resource not found

{
  "error": "string"
}

500 Internal server error

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)

Models¶

Endpoints for retrieving available AI models and default configuration.

List Models¶

POST /api/models

List Models

Returns a list of available AI models/agents that the user can interact with. The list is filtered based on user permissions and agent configuration tags.

Responses

200 Models retrieved successfully

{
  "models": [
    {
      "id": "string",
      "name": "string",
      "description": "string"
    }
  ]
}

[View OpenAPI Spec](../specs/agents.json)

Get Default Configuration¶

GET /api/default-config

Get Default Configuration

Returns the default agent configuration. Used by the Assistant modal to get the default model without showing a dropdown selector.

Responses

200 Default configuration retrieved successfully

{
  "model": "string",
  "model_name": "string",
  "system_prompt": "string"
}

404 Configuration or agent not found

{
  "error": "string"
}

500 Internal server error

{
  "error": "string"
}

[View OpenAPI Spec](../specs/agents.json)