Chat

POST /api/chat

Streams a Gemini chat response as Server-Sent Events (SSE). When RAG is enabled and a userId is provided, the server embeds the latest user message, searches the Qdrant vector store for the five most relevant document chunks (score threshold 0.4), prepends that context to the prompt, and emits a sources event before the first text chunk. The route has a maximum execution time of 60 seconds.

Request body

messages

object[]

required

Conversation history. Each item must have a role and content.

Show Message object

messages[].role

string

required

Either "user" or "assistant".

messages[].content

string

required

The text of the message.

userId

string

The Appwrite user ID. Required for RAG context retrieval. If omitted, the model answers without document context.

useRAG

boolean

default:"true"

Set to false to skip vector search and answer from the model’s general knowledge only.

Response — SSE stream

The response has Content-Type: text/event-stream. Each event is a line starting with data: followed by a JSON payload, terminated by \n\n. Event order:

sources — emitted once at the start, only when relevant document chunks are found.
chunk — emitted repeatedly as the model generates text.
[DONE] — signals the end of the stream.

Sources event

data: {"sources":[{"index":1,"documentId":"abc123","documentName":"report.pdf","documentType":"PDF","score":0.87}]}

sources

object[]

Array of document chunks used as context.

Show Source object

index

number

1-based position in the context list.

documentId

string

Appwrite Storage file ID.

documentName

string

Original file name.

documentType

string

Detected file type, e.g. PDF, MD, TXT.

score

number

Cosine similarity score (0–1). Only chunks above 0.4 are included.

Chunk event

data: {"chunk":"Here is what the document says about"}

chunk

string

A partial text fragment from the model output. Concatenate all chunks to reconstruct the full response.

Done event

data: [DONE]

Error event

data: {"error":"Failed to generate response"}

Example

curl --no-buffer -X POST https://<your-prism-domain>/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Summarise my Q3 report" }
    ],
    "userId": "user_abc123",
    "useRAG": true
  }'

Use --no-buffer with curl to see SSE events as they arrive instead of waiting for the full stream to complete.

POST /api/chat/generate-title

Generates a short title (maximum 5 words) for a chat session by passing the first few user messages to Gemini. Falls back to "New Chat" if generation fails.

Request body

messages

object[]

required

The conversation messages. The endpoint reads only the first three user-role messages. Uses the same { role, content } shape as /api/chat.

Response

{ "title": "Q3 Financial Report Summary" }

title

string

Generated session title, up to 50 characters, with quotes stripped.

Errors

Status	Condition
`400`	`messages` is missing or empty
`500`	Gemini API error

Example

curl -X POST https://<your-prism-domain>/api/chat/generate-title \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What does my Q3 report say about revenue?" }
    ]
  }'

GET /api/chat/history

Returns up to 100 chat sessions for a user, ordered by most recently updated.

Query parameters

userId

string

required

The Appwrite user ID whose sessions to fetch.

Response

{
  "sessions": [
    {
      "$id": "session_xyz",
      "userId": "user_abc123",
      "title": "Q3 Revenue Analysis",
      "messages": "[...]",
      "selectedDocument": "doc_456",
      "createdAt": "2024-11-01T10:00:00.000Z",
      "updatedAt": "2024-11-01T10:45:00.000Z"
    }
  ]
}

sessions

object[]

List of chat session documents from Appwrite.

Show Session object

$id

string

Appwrite document ID for the session.

userId

string

Owner’s Appwrite user ID.

title

string

Display title for the session.

messages

string

JSON-serialised array of message objects.

selectedDocument

string

Appwrite file ID of the document pinned to this session, or null.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Errors

Status	Condition
`400`	`userId` query parameter is missing
`500`	Appwrite database error

Example

curl "https://<your-prism-domain>/api/chat/history?userId=user_abc123"

POST /api/chat/history

Creates a new chat session document in Appwrite.

Request body

userId

string

required

The Appwrite user ID to associate with the session.

messages

object[]

required

Initial message array. Stored as a JSON string in Appwrite.

title

string

default:"New Chat"

Display title for the session.

selectedDocument

string

Appwrite file ID of a document to pin to this session.

Response

{ "session": { "$id": "session_xyz", "title": "New Chat", "..." } }

session

object

The newly created Appwrite document. Includes all session fields listed under GET /api/chat/history.

Errors

Status	Condition
`400`	`userId` or `messages` is missing
`500`	Appwrite database error

Example

curl -X POST https://<your-prism-domain>/api/chat/history \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123",
    "title": "Revenue Discussion",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

PUT /api/chat/history

Updates an existing chat session. Only the fields you include in the body are changed; omitted fields are left unchanged.

Request body

sessionId

string

required

Appwrite document ID of the session to update.

title

string

New display title.

messages

object[]

Replacement message array. Overwrites the stored messages entirely.

selectedDocument

string

New pinned document file ID, or null to clear.

Response

{ "session": { "$id": "session_xyz", "title": "Updated Title", "..." } }

Errors

Status	Condition
`400`	`sessionId` is missing
`500`	Appwrite database error

Example

curl -X PUT https://<your-prism-domain>/api/chat/history \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_xyz",
    "title": "Q3 Deep Dive"
  }'

DELETE /api/chat/history

Permanently deletes a chat session from Appwrite.

Query parameters

sessionId

string

required

Appwrite document ID of the session to delete.

Response

{ "success": true }

Errors

Status	Condition
`400`	`sessionId` query parameter is missing
`500`	Appwrite database error

Example

curl -X DELETE \
  "https://<your-prism-domain>/api/chat/history?sessionId=session_xyz"

API Overview

Endpoints

POST /api/chat

Request body

Response — SSE stream

Example

POST /api/chat/generate-title

Request body

Response

Errors

Example

GET /api/chat/history

Query parameters

Response

Errors

Example

POST /api/chat/history

Request body

Response

Errors

Example

PUT /api/chat/history

Request body

Response

Errors

Example

DELETE /api/chat/history

Query parameters

Response

Errors

Example

Build docs developers (and LLMs) love

API Overview

Endpoints

​POST /api/chat

​Request body

​Response — SSE stream

​Example

​POST /api/chat/generate-title

​Request body

​Response

​Errors

​Example

​GET /api/chat/history

​Query parameters

​Response

​Errors

​Example

​POST /api/chat/history

​Request body

​Response

​Errors

​Example

​PUT /api/chat/history

​Request body

​Response

​Errors

​Example

​DELETE /api/chat/history

​Query parameters

​Response

​Errors

​Example

Build docs developers (and LLMs) love

POST /api/chat

Request body

Response — SSE stream

Example

POST /api/chat/generate-title

Request body

Response

Errors

Example

GET /api/chat/history

Query parameters

Response

Errors

Example

POST /api/chat/history

Request body

Response

Errors

Example

PUT /api/chat/history

Request body

Response

Errors

Example

DELETE /api/chat/history

Query parameters

Response

Errors

Example