Documents

POST /api/documents/index

Downloads a file from Appwrite Storage, extracts its text (or generates an AI image description for image files), splits the text into overlapping chunks, generates 768-dimension embeddings with Gemini text-embedding-004, detects a category, and upserts all chunk vectors into the Qdrant prism_documents collection. This is the most expensive endpoint. It has a maximum execution time of 300 seconds.

Call this endpoint once per file, immediately after uploading to Appwrite Storage. Re-indexing a file that already has vectors will add duplicate entries.

Request body

documentId

string

required

The Appwrite Storage file ID. Used to download the file and as the primary identifier for all vector payloads.

userId

string

required

The Appwrite user ID. Stored as a payload field on every vector so that searches can be scoped per user.

fileName

string

required

The original file name including extension (e.g. report.pdf). Used to detect file type and category.

Chunking behaviour

Text documents are split with a maximum chunk size of 1000 characters and an overlap of 200 characters. Markdown files are additionally split on header boundaries. Image files (jpg, jpeg, png, gif, webp, bmp, svg) bypass text extraction and are described by Gemini Vision instead.

Response

{
  "success": true,
  "documentId": "file_abc123",
  "documentName": "report.pdf",
  "chunks": 14,
  "category": "Financial",
  "message": "Document indexed successfully"
}

success

boolean

true on success.

documentId

string

Echo of the supplied Appwrite file ID.

documentName

string

File name as stored in Appwrite.

chunks

number

Number of text chunks indexed into Qdrant.

Errors

Status	Condition
`400`	Any of `documentId`, `userId`, or `fileName` is missing
`400`	No extractable text found in the file
`500`	Appwrite Storage download failed, Gemini embedding failed, or Qdrant upsert failed

Example

curl -X POST https://<your-prism-domain>/api/documents/index \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "file_abc123",
    "userId": "user_abc123",
    "fileName": "report.pdf"
  }'

POST /api/documents/delete

Deletes all Qdrant vector points associated with a document. This does not delete the file from Appwrite Storage — remove the file from Storage separately using the Appwrite SDK or console. The route has a maximum execution time of 60 seconds.

Request body

documentId

string

required

The Appwrite Storage file ID whose vectors to delete.

Response

{
  "success": true,
  "message": "Document deleted from vector database"
}

success

boolean

true when the delete operation completes.

message

string

Human-readable confirmation.

Errors

Status	Condition
`400`	`documentId` is missing
`500`	Qdrant delete operation failed

Example

curl -X POST https://<your-prism-domain>/api/documents/delete \
  -H "Content-Type: application/json" \
  -d '{"documentId": "file_abc123"}'

POST /api/documents/rename

Renames a file in Appwrite Storage and updates the documentName payload field on all matching Qdrant vectors in a single setPayload call. Both operations run synchronously.

Request body

documentId

string

required

The Appwrite Storage file ID to rename.

newName

string

required

The new file name. Must not be empty or blank, and must be 255 characters or fewer.

Response

{
  "success": true,
  "documentId": "file_abc123",
  "newName": "q3-report-final.pdf",
  "message": "File renamed successfully"
}

success

boolean

true on success.

documentId

string

Echo of the Appwrite file ID.

newName

string

The name that was applied.

message

string

Human-readable confirmation.

Errors

Status	Condition
`400`	`documentId` or `newName` is missing
`400`	`newName` is blank or exceeds 255 characters
`500`	Appwrite Storage update failed

Example

curl -X POST https://<your-prism-domain>/api/documents/rename \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "file_abc123",
    "newName": "q3-report-final.pdf"
  }'

GET /api/documents/content

Downloads a file from Appwrite Storage and returns its raw bytes decoded as UTF-8 text. Intended for plain-text file types such as .txt, .md, and .csv.

Binary formats (PDF, DOCX, images) are not decoded before being returned. This endpoint is suitable for text files only.

Query parameters

fileId

string

required

The Appwrite Storage file ID to retrieve.

Response

Returns the file bytes as text/plain; charset=utf-8. The response body is the raw file content, not JSON.

Errors

Status	Condition
`400`	`fileId` query parameter is missing
`500`	Appwrite Storage download failed

Example

curl "https://<your-prism-domain>/api/documents/content?fileId=file_abc123"

GET /api/documents/recommendations

Finds documents in the user’s library that are semantically similar to the specified document. The endpoint fetches a representative vector from the source document, runs a Qdrant similarity search excluding the source document itself, and filters results to those that still exist in Appwrite Storage. The route has a maximum execution time of 60 seconds.

Query parameters

documentId

string

required

The Appwrite file ID of the source document to find recommendations for.

userId

string

required

The Appwrite user ID. Restricts recommendations to the user’s own documents.

limit

number

default:"5"

Maximum number of recommendations to return. The server fetches limit * 2 candidates internally, validates each against Appwrite Storage, and returns the first limit valid results.

Response

{
  "success": true,
  "recommendations": [
    {
      "documentId": "file_def456",
      "documentName": "q2-report.pdf",
      "documentType": "PDF",
      "category": "Financial",
      "score": 0.81,
      "matchingChunks": [
        { "text": "Revenue grew 12% year-over-year…", "score": 0.81 },
        { "text": "Operating costs remained stable…", "score": 0.77 }
      ]
    }
  ],
  "count": 1
}

success

boolean

true on success.

recommendations

object[]

Ordered list of similar documents, highest similarity first. Only documents with a cosine similarity score of 0.5 or above are included.

Show Recommendation object

documentId

string

Appwrite file ID of the recommended document.

documentName

string

File name of the recommended document.

documentType

string

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

Errors

Status	Condition
`400`	`documentId` is missing
`400`	`userId` is missing
`500`	Qdrant or Appwrite error

Example

curl "https://<your-prism-domain>/api/documents/recommendations?documentId=file_abc123&userId=user_abc123&limit=3"

API Overview

Endpoints

POST /api/documents/index

Request body

Chunking behaviour

Response

Errors

Example

POST /api/documents/delete

Request body

Response

Errors

Example

POST /api/documents/rename

Request body

Response

Errors

Example

GET /api/documents/content

Query parameters

Response

Errors

Example

GET /api/documents/recommendations

Query parameters

Response

Errors

Example

Build docs developers (and LLMs) love

API Overview

Endpoints

​POST /api/documents/index

​Request body

​Chunking behaviour

​Response

​Errors

​Example

​POST /api/documents/delete

​Request body

​Response

​Errors

​Example

​POST /api/documents/rename

​Request body

​Response

​Errors

​Example

​GET /api/documents/content

​Query parameters

​Response

​Errors

​Example

​GET /api/documents/recommendations

​Query parameters

​Response

​Errors

​Example

Build docs developers (and LLMs) love

POST /api/documents/index

Request body

Chunking behaviour

Response

Errors

Example

POST /api/documents/delete

Request body

Response

Errors

Example

POST /api/documents/rename

Request body

Response

Errors

Example

GET /api/documents/content

Query parameters

Response

Errors

Example

GET /api/documents/recommendations

Query parameters

Response

Errors

Example