API Reference
Collections
API endpoints for managing collections.
Base path: /v1/collections
List Collections
GET /v1/collectionsQuery parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | — | Filter by name prefix (case-insensitive) |
limit | integer | 100 | Results per page (1–1,000) |
offset | integer | 0 | Pagination offset |
Response 200:
{
"collections": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "research_papers",
"description": "Academic research papers",
"embedding_provider": "openai",
"embedding_model": "text-embedding-3-small",
"dimension": 1536,
"chunk_size": 512,
"chunk_overlap": 50,
"document_count": 15,
"has_api_key": false,
"reranking_enabled": false,
"reranking_model": "rerank-v3.5",
"has_reranking_api_key": false,
"default_top_k": 10,
"default_min_score": null,
"default_search_mode": "semantic",
"metadata": {},
"created_at": "2026-04-01T00:00:00Z",
"updated_at": "2026-04-01T12:00:00Z"
}
],
"total": 1
}Create Collection
POST /v1/collectionsRequest body:
{
"name": "research_papers",
"description": "Academic research papers",
"embedding_provider": "openai",
"embedding_model": "text-embedding-3-small",
"dimension": 1536,
"chunk_size": 512,
"chunk_overlap": 50,
"default_top_k": 10,
"default_min_score": 0.3,
"default_search_mode": "semantic",
"metadata": { "team": "research" }
}| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
name | string | yes | — | 1-128 chars, [a-zA-Z][a-zA-Z0-9_]* |
description | string | no | "" | — |
embedding_provider | string | no | Server default | openai, cohere |
embedding_model | string | no | Server default | Model name |
embedding_api_key | string | no | — | Required for openai, cohere |
dimension | integer | no | Server default | Embedding vector dimension |
chunk_size | integer | no | 512 | 64–10,000 |
chunk_overlap | integer | no | 50 | 0–5,000, must be < chunk_size |
default_top_k | integer | no | 10 | 1–1,000 |
default_min_score | float | no | null | Minimum similarity score |
default_search_mode | string | no | "semantic" | semantic, keyword, hybrid |
reranking_enabled | boolean | no | false | Enable reranking |
reranking_model | string | no | "rerank-v3.5" | Cohere reranking model |
reranking_api_key | string | no | — | Cohere API key |
metadata | object | no | {} | Arbitrary key-value pairs |
Response 201: Full collection object.
Errors:
400— Invalid name format, invalid chunk config409— Collection name already exists
Get Collection
GET /v1/collections/{name}Response 200: Full collection object.
Errors: 404 — Collection not found
Get Collection Stats
GET /v1/collections/{name}/statsLightweight endpoint returning document and chunk counts for a single collection.
Response 200:
{
"collection": "research_papers",
"document_count": 15,
"total_chunks": 482,
"total_tokens": 125000,
"total_size_bytes": 52428800,
"status_counts": {
"ready": 12,
"pending": 2,
"processing": 1,
"failed": 0
}
}Errors: 404 — Collection not found
Update Collection
PUT /v1/collections/{name}Request body:
{
"description": "Updated description",
"metadata": { "team": "engineering" },
"reranking_enabled": true,
"default_top_k": 20,
"default_search_mode": "hybrid",
}| Field | Type | Required | Notes |
|---|---|---|---|
description | string | no | Pass null to keep current |
metadata | object | no | Pass null to keep current |
reranking_enabled | boolean | no | Enable/disable reranking |
reranking_model | string | no | Cohere reranking model |
reranking_api_key | string | no | Cohere API key |
default_top_k | integer | no | Default results count (1–1,000) |
default_min_score | float | no | Default minimum similarity score |
default_search_mode | string | no | semantic, keyword, hybrid |
Response 200: Updated collection object.
Errors: 404 — Collection not found
Delete Collection
DELETE /v1/collections/{name}Deletes the collection and all its documents and vectors.
Response 200:
{
"status": "ok",
"message": "Collection 'research_papers' deleted"
}Errors: 404 — Collection not found