> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useskald.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> API reference for the chat /api/v1/chat endpoint

## Chat API

Ask questions about your knowledge base using an AI agent with optional filtering to focus the search context.

### POST /api/v1/chat

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Request (using Project API Key):**

```json theme={null}
{
    "query": "What were the main points discussed in the Q1 meeting?",
    "stream": false,
    "system_prompt": "You are a helpful assistant that can answer questions about the memo.",
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "meeting-notes",
            "filter_type": "native_field"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["q1", "meeting"],
            "filter_type": "native_field"
        }
    ]
}
```

**Request (using Token Authentication):**

```json theme={null}
{
    "query": "What were the main points discussed in the Q1 meeting?",
    "project_id": "project-uuid",
    "stream": false,
    "filters": [
        {
            "field": "category",
            "operator": "eq",
            "value": "meeting",
            "filter_type": "custom_metadata"
        }
    ]
}
```

**Parameters:**

* `query` (string, required): The question to ask
* `project_id` (UUID, optional): **Only required when using Token Authentication**
* `stream` (boolean, optional): Enable streaming responses (default: false)
* `system_prompt` (string, optional): A system prompt to guide the chat agent's behavior
* `filters` (array of filter objects, optional): Filters to narrow the search context. See [Filters](/docs/api-reference/filters) for detailed documentation.

**Filter Support:**

Filters are applied during the initial retrieval of relevant context, allowing you to:

* Filter by a "workspace" or "team" ID from your side
* Focus the chat on specific sources (e.g., only Notion docs)
* Query only memos with certain tags
* Exclude certain categories of content

See [Filters](/docs/api-reference/filters) for complete documentation on filter structure, operators, and examples.

**Response (Non-streaming):**

```json theme={null}
{
    "ok": true,
    "response": "The main points discussed in the Q1 meeting were:\n1. Revenue targets \n2. Hiring plans \n3. Product roadmap",
    "intermediate_steps": []
}
```

**Response (Streaming):**

When `stream: true`, returns Server-Sent Events:

```
Content-Type: text/event-stream

: ping

data: {"type": "token", "content": "The"}

data: {"type": "token", "content": " main"}

data: {"type": "done"}
```

### GET /api/v1/chat

Get a list of chats.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Query Parameters:**

* `page` (integer, optional): Page number (default: 1)
* `page_size` (integer, optional): Page size (default: 20)

**Example Response:**

```json theme={null}
{
    "results": [
        {
            "uuid": "84365e7e-381e-47da-9104-8dcc7a83920e",
            "created_at": "2025-12-13T16:57:45.240Z",
            "title": "What does undefined do?",
            "message_count": 2,
            "last_message_at": "2025-12-13T16:57:45.242Z"
        }
    ],
    "count": 1,
    "page": 1,
    "page_size": 1,
    "total_pages": 1
}
```

* Count: The total number of chats
* Page: The page number
* Page size: The number of chats per page
* Total pages: The total number of pages

### GET /api/v1/chat/:chat\_uuid

Get a chat by its UUID.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Path Parameters:**

* `:chat_uuid` (string, required): The UUID of the chat

**Example Response:**

```json theme={null}
{
    "uuid": "4a71fd8b-2ca0-42d8-9bfd-8d11d080ecf3",
    "created_at": "2025-11-22T01:13:41.113Z",
    "messages": [
        {
            "uuid": "e03af6a7-da4d-4508-9057-4dcc25eec7e0",
            "content": "what's 2+2?",
            "sent_by": "user",
            "sent_at": "2025-11-22T01:13:41.114Z",
            "client_system_prompt": null
        },
        {
            "uuid": "d72c88d0-c6d4-4155-8601-c695abac5cab",
            "content": "2+2 is 4",
            "sent_by": "model",
            "sent_at": "2025-11-22T01:13:41.115Z",
            "client_system_prompt": null
        }
    ]
}
```

### Error Responses

**Missing query (400):**

```json theme={null}
{
    "error": "Query is required"
}
```

**Invalid filters (400):**

```json theme={null}
{
    "error": "Filters must be a list"
}
```

**Invalid filter structure (400):**

```json theme={null}
{
    "error": "Invalid filter: <specific error message>"
}
```

**Agent error (500):**

```json theme={null}
{
    "error": "Agent error: <error details>"
}
```