Documents API

Authentication

Viewer role or above for reads, Editor or above for creating and modifying collections. See API overview.

Collections

A collection is a named bag of documents. Each collection can be attached to one or more chatbots as knowledge. See Documents for the dashboard counterpart.

GET /api/documents/collections

List all document collections visible to the caller.

Response: an array of collection objects with id, name, description, document count, total bytes indexed, and timestamps.

POST /api/documents/collections

Create a new collection.

Request body: a collection object with at least name. Optional: description.

Response: 201 Created with the new collection.

PUT /api/documents/collections/{id}

Update a collection’s metadata. You can change the name and description; contents are managed via the upload endpoint.

Response: the updated collection object.

DELETE /api/documents/collections/{id}

Delete a collection and all its documents. Any chatbots linked to this collection lose their knowledge attachment and revert to ungrounded responses.

Query parameters:

Response: 204 No Content.

Documents

GET /api/documents/collections/{collectionId}/documents

List all documents inside a collection.

Response: an array of document metadata objects with id, filename, size, indexing status, chunk count, and timestamps.

POST /api/documents/collections/{collectionId}/upload

Upload a document into a collection. Expects multipart/form-data with a file field. Supported formats: Markdown, plain text, PDF, and most plain-text formats.

curl -X POST https://your-exolvra.example/api/documents/collections/coll_abc/upload \
  -H "Authorization: Bearer exou_..." \
  -F "file=@./handbook.pdf"

Response: the new document metadata object. The document starts in Uploading status, transitions to Indexing while chunks are generated and embedded, and lands in Ready once searchable.

Large documents take longer to index — don’t assume a file is ready until its status flips to Ready.

DELETE /api/documents/doc/{id}

Delete a single document from its collection. The document and all its chunks are removed from the index; any chatbots linked to the parent collection will no longer retrieve from this file.

Response: 204 No Content.

POST /api/documents/collections/{collectionId}/reindex

Rebuild the index for an entire collection. Useful when you’ve changed the embedding model or detected corruption in the existing index.

Query parameters:

Response: a job summary with the number of documents queued for reindexing. The actual reindex runs in the background.

Search

POST /api/documents/search

Run a semantic search across one or more collections and return the top matching chunks.

Request body:

{
  "query": "How do I reset my password?",
  "collectionIds": ["coll_abc"],
  "maxResults": 10
}

Response: an array of chunk objects with the matched text, source document id, chunk id, and relevance score. Chatbots use this same API internally when they do RAG retrieval on every turn.

{
  "results": [
    {
      "documentId": "doc_xyz",
      "chunkId": "chunk_01",
      "text": "To reset your password, go to Settings → Security...",
      "score": 0.89,
      "sourceFilename": "user-guide.md"
    }
  ]
}

Use this endpoint when you want to test retrieval quality without spinning up a chatbot — feed in representative queries, see which chunks come back, and iterate on your source material based on what’s not surfacing.

Example — upload, test retrieval, attach

# Create a collection
curl -X POST https://your-exolvra.example/api/documents/collections \
  -H "Authorization: Bearer exou_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "product-handbook", "description": "Our internal product docs"}'

# Upload a document
curl -X POST https://your-exolvra.example/api/documents/collections/product-handbook/upload \
  -H "Authorization: Bearer exou_..." \
  -F "file=@./pricing-faq.md"

# Wait for indexing to complete, then test retrieval
curl -X POST https://your-exolvra.example/api/documents/search \
  -H "Authorization: Bearer exou_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How much does the Pro tier cost?",
    "collectionIds": ["product-handbook"],
    "maxResults": 5
  }'

If the query returns the chunks you expect, attach the collection to a chatbot via the Bots dashboard or API and it’ll use the same retrieval on every user message.

Where to go next

• Documents — the dashboard counterpart
• Memory & knowledge — how collections differ from memory
• Bots — attaching a collection to a chatbot