Collections (RAG) API

Collections store vectorized document chunks for retrieval-augmented generation.

Create Collection

POST /v1/collections

Request Body

{
  "name": "Support Knowledge Base",
  "description": "Customer support articles and FAQs",
  "metadata": { "team": "support" }
}

Field	Type	Required	Description
name	string	yes	1-100 characters
description	string	no	Up to 500 characters
metadata	object	no	Arbitrary key-value pairs

Response 201

{
  "id": "coll_abc123",
  "name": "Support Knowledge Base",
  "description": "Customer support articles and FAQs",
  "metadata": { "team": "support" },
  "createdAt": "2026-03-21T00:00:00.000Z"
}

List Collections

GET /v1/collections?limit=20&cursor=coll_xyz

Response 200

{
  "data": [{ "id": "coll_abc123", "name": "Support Knowledge Base", "..." : "..." }],
  "nextCursor": "coll_xyz",
  "hasMore": false
}

Get Collection

GET /v1/collections/:id

Response 200

Full collection object.

Delete Collection

DELETE /v1/collections/:id

Removes the collection and all documents/chunks within it.

Response 204

No content.

Ingest Content

Add content to a collection. Content is chunked and embedded for vector search.

POST /v1/collections/:id/ingest

Request Body

{
  "content": "Our return policy allows returns within 30 days...",
  "contentType": "text",
  "chunkSize": 1000,
  "chunkOverlap": 200,
  "metadata": {
    "source": "faq",
    "category": "returns"
  }
}

Field	Type	Default	Description
content	string	-	Text content (up to 1MB)
sourceUrl	string	-	URL for audio content type
contentType	string	"text"	text, transcript, audio, url
chunkSize	number	1000	Characters per chunk (100-4000)
chunkOverlap	number	200	Overlap between chunks (0-500, must be < chunkSize)
metadata	object	-	Attached to all chunks from this document

Response 201

{
  "documentId": "doc_abc123",
  "chunksCreated": 5,
  "tokensUsed": 1250
}

Search Collection

Query a collection for relevant content.

POST /v1/collections/:id/search

Request Body

{
  "query": "what is the return policy?",
  "limit": 5,
  "threshold": 0.7,
  "includeMetadata": true
}

Field	Type	Default	Description
query	string	required	Search query (1-2000 chars)
limit	number	10	Max results (1-100)
threshold	number	0.7	Minimum similarity score (0-1)
includeMetadata	boolean	true	Include chunk metadata in results

Response 200

{
  "results": [
    {
      "content": "Returns are accepted within 30 days of purchase with a valid receipt...",
      "score": 0.92,
      "metadata": { "source": "faq", "category": "returns" },
      "documentId": "doc_abc123",
      "chunkIndex": 2
    }
  ]
}

Delete Document

Remove a single document and its chunks from a collection.

DELETE /v1/collections/:collectionId/documents/:documentId

Response 204

No content.