Documents

Documents are JSON objects stored in an index. Headband auto-detects schema from the document structure -- no upfront schema definition required. You can send thousands of documents in a single request for bulk ingestion.

GET/v1/documents?index=products

List documents in an index with pagination.

Supports limit and offset query parameters for pagination. Use server-side only; search keys cannot browse raw source documents.

Auth admin key onlyReturns 200
Response
{
  "results": [
    { "id": 1, "title": "MacBook Pro", "price": 1999 },
    { "id": 2, "title": "iPhone 16", "price": 999 }
  ],
  "total": 19547,
  "limit": 20,
  "offset": 0
}
GET/v1/documents/:id?index=products

Get a single document by its primary key.

Use server-side only; search keys cannot browse raw source documents.

Auth admin key onlyReturns 200
Response
{
  "id": 1,
  "title": "MacBook Pro",
  "price": 1999,
  "category": "laptops"
}
POST/v1/documents?index=products&primaryKey=id

Add or replace documents in an index. If a document with the same primary key already exists, it will be replaced.

Supports bulk upload -- send thousands of documents in one request.

Auth admin key onlyReturns 202
Request body
[
  { "id": 1, "title": "MacBook Pro", "price": 1999, "category": "laptops" },
  { "id": 2, "title": "iPhone 16", "price": 999, "category": "phones" }
]
Response
{
  "taskUid": 2,
  "indexUid": "products",
  "status": "enqueued",
  "enqueuedAt": "2025-01-15T09:00:00Z"
}
DELETE/v1/documents?index=products

Delete documents from an index by IDs or by filter.

Auth admin key onlyReturns 202
Request body
// Delete by IDs:
{ "ids": [1, 2] }

// Or delete by filter:
{ "filter": "price > 1000" }
Response
{
  "taskUid": 3,
  "indexUid": "products",
  "status": "enqueued"
}

Bulk Import

Import large volumes of documents efficiently. The bulk endpoint automatically splits your documents into optimized batches and sends them in parallel, handling payloads of up to 500K documents in a single request.

POST/v1/bulk

Import documents in optimized parallel batches.

Auth admin key onlyReturns 202
Request body
{
  "index": "products",
  "primaryKey": "id",
  "documents": [
    { "id": 1, "title": "Widget", "price": 9.99 },
    { "id": 2, "title": "Gadget", "price": 24.99 }
    // ... up to 500K documents
  ]
}
Response
{
  "tasks": [
    { "taskUid": 10, "indexUid": "products", "status": "enqueued", "batchNumber": 1, "documentsInBatch": 10000 },
    { "taskUid": 11, "indexUid": "products", "status": "enqueued", "batchNumber": 2, "documentsInBatch": 10000 }
  ],
  "totalDocuments": 20000,
  "totalBatches": 2,
  "batchSize": 10000
}
ParameterTypeDefaultDescription
batchSizenumber10000Documents per batch (min 100, max 50000).

Streaming Progress

POST/v1/bulk/stream

Import documents with real-time Server-Sent Events progress. Same request body as /v1/bulk.

Use the streaming endpoint for large imports to get real-time progress feedback. Combine with the Tasks API to poll individual batch status after import.

Auth admin key onlyReturns 200 (SSE stream)
Request body
{
  "index": "products",
  "primaryKey": "id",
  "documents": [
    { "id": 1, "title": "Widget", "price": 9.99 },
    { "id": 2, "title": "Gadget", "price": 24.99 }
    // ... up to 500K documents
  ]
}
Response
data: {"event":"batch_complete","batchNumber":1,"taskUid":10,"documentsInBatch":10000}

data: {"event":"batch_complete","batchNumber":2,"taskUid":11,"documentsInBatch":10000}

data: {"event":"complete","totalDocuments":20000,"totalBatches":2}