Chat

A Chat session (/chat) is a stateful conversation thread. Unlike the one-off Search API, a chat maintains message history, allowing for multi-turn reasoning and follow-up questions grounded in your Knowledge Base.

🤖 The RAG Agent Workflow

Our conversational engine uses an AI Agent that can "think" before answering. It constructs retrieval queries, analyzes the results, and cites its sources in real-time.

 ┌──────────────┐     ┌──────────────┐     ┌───────────────┐     ┌──────────────┐
 │  User Query  │ ───►│ Agent Tool   │ ───►│ Context Pack  │ ───►│ LLM Streams  │
 │  "How to..." │     │ (Retrieval)  │     │ (Doc Chunks)  │     │ ApiResponse  │
 └──────────────┘     └──────────────┘     └───────────────┘     └──────────────┘

The agent executes a multi-stage reasoning process:

Thought & Reasoning: The agent may generate a "reasoning" block (visible in the API as type: "reasoning") where it plans its retrieval strategy.
Contextual Tool Call: The agent uses a specialized retrieve tool to perform a Hybrid Search across your collection.
Grounded Response: The final answer is synthesized using the retrieved chunks.
Live Citations: The streaming API delivers a structured array of Citations containing Document IDs and snippets, ensuring every claim is backed by your data.

🛠️ Chat Management

Chat sessions are stateful and belong to a Workspace. For a detailed technical reference of every field and parameter, see the API Chat Reference.

Create a Chat

Initialize a new conversation thread. You must provide a collection_id which defines the search scope for the entire session.

curl -X POST "https://api.axelered.com/v1/w/{workspace_id}/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Onboarding Support",
    "collection_id": "{collection_id}"
  }'

Send a Message

Send a new query to an existing chat. By default, this endpoint returns a stream of NDJSON chunks containing tokens, reasoning, and citations.

curl -X POST "https://api.axelered.com/v1/w/{workspace_id}/chat/{chat_id}/message" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the rules for parental leave?",
    "stream": true
  }'

Read, List & History

To manage your conversation threads and retrieve historical context, use the following specialized endpoints:

List Chats: Retrieve all active chat sessions within the workspace.
Read Chat: Fetch metadata for a specific chat session.
List History: Retrieve the complete message history for a conversation, including AI reasoning and citations.

Delete a Chat

Chats use soft-deletion. When deleted, they are hidden from listings, but their history is preserved and can be restored if necessary.

curl -X DELETE "https://api.axelered.com/v1/w/{workspace_id}/chat/{chat_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

🌊 Streaming Protocol

The /message endpoint uses NDJSON (Newline Delimited JSON) to stream state updates. Each chunk represents a differential update to the conversation state, following the diffcp protocol.

This protocol allows your UI to efficiently render tokens, reasoning steps, and citations as they are generated by applying incremental patches to the local chat state.