Skip to main content
The chat endpoints let you send questions against ingested documents, browse conversation history, and remove past conversations.

​
Query documents

Requires authentication.
POST /api/v1/chat/completions Sends a message to the retrieval-augmented generation pipeline and returns an answer grounded in the documents associated with the session.

​
Request body

​
message
string
required
The user’s question or prompt.
​
sessionId
string
required
The session to query against. Documents ingested into this session are used as the retrieval source.
​
institution
string
Optional filter to restrict retrieval to documents tagged with a specific institution.

​
Response

​
200 OK

​
success
boolean
Always true on a successful response.
​
data
string
The generated answer text.

​
500 Internal Server Error

​
success
boolean
Always false.
​
error
string
Always "Internal Server Error".

​
Example

curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were the key findings in Q3?",
    "sessionId": "sess_abc123",
    "institution": "finance-dept"
  }'
Response
{
  "success": true,
  "data": "The key findings in Q3 included a 12% increase in revenue..."
}

​
Get chat history

GET /api/v1/chat/history/:sessionId Returns paginated chat messages for a session, ordered from oldest to newest. Each page contains up to 20 messages.

​
Path parameters

​
sessionId
string
required
The session whose history you want to retrieve.

​
Query parameters

​
page
number
default:"0"
Zero-based page index. Defaults to 0 (the first page). Values below 0 are clamped to 0.

​
Response

​
200 OK

​
success
boolean
Always true.
​
data
array
Array of chat message objects for the requested page.

​
Example

curl -X GET "http://localhost:3000/api/v1/chat/history/sess_abc123?page=0" \
  -H "Authorization: Bearer <token>"
Response
{
  "success": true,
  "data": [
    {
      "role": "user",
      "content": "What were the key findings in Q3?",
      "createdAt": "2026-04-01T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "The key findings in Q3 included a 12% increase in revenue...",
      "createdAt": "2026-04-01T10:00:02Z"
    }
  ]
}

​
Delete chat

This permanently deletes all messages in the session. This action cannot be undone.
DELETE /api/v1/chat/:sessionId Deletes all chat messages associated with a session.

​
Path parameters

​
sessionId
string
required
The session whose chat history you want to delete.

​
Response

​
204 No Content

Returned on success. The response body is empty.

​
400 Bad Request

​
error
string
"Session deletion failed" — returned when the delete operation could not be completed.

​
Example

curl -X DELETE http://localhost:3000/api/v1/chat/sess_abc123 \
  -H "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us