Skip to main content

​
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 Request (using Project API Key): 
{
    "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): 
{
    "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 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 for complete documentation on filter structure, operators, and examples. Response (Non-streaming): 
{
    "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 Query Parameters:
  • page (integer, optional): Page number (default: 1)
  • page_size (integer, optional): Page size (default: 20)
Example Response: 
{
    "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 Path Parameters:
  • :chat_uuid (string, required): The UUID of the chat
Example Response: 
{
    "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): 
{
    "error": "Query is required"
}
Invalid filters (400): 
{
    "error": "Filters must be a list"
}
Invalid filter structure (400): 
{
    "error": "Invalid filter: <specific error message>"
}
Agent error (500): 
{
    "error": "Agent error: <error details>"
}