Documents

Documents are the JSON objects stored in an index. Each document must include the primary key field defined when the index was created.

POST /v1/indices/{uid}/documents Admin key

Add or replace documents. If a document with the same primary key exists, it is replaced entirely.

Request body

A JSON array of documents (or a single object). Each must include the primary key field.

text
curl -X POST https://search.example.com/v1/indices/products/documents \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '[
    { "id": "1", "title": "Running Shoes", "brand": "Nike", "price": 12000 },
    { "id": "2", "title": "Trail Runners", "brand": "Salomon", "price": 16000 }
  ]'

SDK

text
await idx.addDocuments([
  { id: '1', title: 'Running Shoes', brand: 'Nike', price: 12000 },
  { id: '2', title: 'Trail Runners', brand: 'Salomon', price: 16000 },
]);

Response 200 OK

text
{ "indexed": 2 }
GET /v1/indices/{uid}/documents Admin key

List documents with offset-based pagination.

Query parameters

ParameterTypeDescription
limit optionalnumberMaximum documents to return.
Default: 20
offset optionalnumberNumber of documents to skip.
Default: 0

Response 200 OK

text
{
  "results": [
    { "id": "1", "title": "Running Shoes", "brand": "Nike" }
  ],
  "total": 500,
  "limit": 20,
  "offset": 0
}
GET /v1/indices/{uid}/documents/{doc_id} Admin key

Retrieve a single document by its primary key value.

Path parameters

ParameterTypeDescription
uid requiredstringThe index UID.
doc_id requiredstringThe document primary key value.

SDK

text
const doc = await idx.getDocument('1');

Response 200 OK

text
{
  "id": "1",
  "title": "Running Shoes",
  "brand": "Nike",
  "price": 12000
}
PATCH /v1/indices/{uid}/documents Admin key

Partially update documents. Provided fields are merged; omitted fields are preserved.

Each document in the array must include the primary key. Only the fields you include will be updated. All other fields on the existing document remain unchanged.

text
curl -X PATCH https://search.example.com/v1/indices/products/documents \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '[{ "id": "1", "price": 11000 }]'

SDK

text
await idx.updateDocuments([{ id: '1', price: 11000 }]);

Response 200 OK

text
{ "indexed": 1 }
DELETE /v1/indices/{uid}/documents/{doc_id} Admin key

Delete a single document by primary key.

SDK

text
await idx.deleteDocument('1');

Response 204 No Content

POST /v1/indices/{uid}/documents/delete-batch Admin key

Delete multiple documents by a list of primary key values.

Request body

ParameterTypeDescription
ids requiredstring[]Array of document IDs to delete. Maximum 1,000.
text
curl -X POST https://search.example.com/v1/indices/products/documents/delete-batch \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["1", "2", "3"] }'

SDK

text
await idx.deleteBatch({ ids: ['1', '2', '3'] });

Response 200 OK

text
{ "deleted": 3 }
POST /v1/indices/{uid}/documents/delete-by-filter Admin key

Delete all documents matching a filter expression.

Request body

ParameterTypeDescription
filter requiredstringFilter expression. See the Filtering guide for syntax.
Safety limit
If the filter matches more than 100,000 documents, the request will fail with an error. Narrow your filter or delete in batches.
text
curl -X POST https://search.example.com/v1/indices/products/documents/delete-by-filter \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "filter": "status = '\''archived'\'' AND price < 1000" }'

SDK

text
await idx.deleteByFilter({ filter: "status = 'archived' AND price < 1000" });

Response 200 OK

text
{ "deleted": 50 }

Limits

ParameterTypeDescription
Batch size optionalconstraintMaximum 1,000 documents per upsert or delete-batch request.
Document size optionalconstraintMaximum 100 KB per document (serialized JSON).
Fields per document optionalconstraintMaximum 200 fields per document.
Delete-by-filter optionalconstraintMaximum 100,000 matching documents per request.