Documents
Documents are the JSON objects stored in an index. Each document must include the primary key field defined when the index was created.
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.
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
await idx.addDocuments([ { id: '1', title: 'Running Shoes', brand: 'Nike', price: 12000 }, { id: '2', title: 'Trail Runners', brand: 'Salomon', price: 16000 }, ]);
Response 200 OK
{ "indexed": 2 }List documents with offset-based pagination.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit optional | number | Maximum documents to return. Default: 20 |
| offset optional | number | Number of documents to skip. Default: 0 |
Response 200 OK
{
"results": [
{ "id": "1", "title": "Running Shoes", "brand": "Nike" }
],
"total": 500,
"limit": 20,
"offset": 0
}Retrieve a single document by its primary key value.
Path parameters
| Parameter | Type | Description |
|---|---|---|
| uid required | string | The index UID. |
| doc_id required | string | The document primary key value. |
SDK
const doc = await idx.getDocument('1');
Response 200 OK
{
"id": "1",
"title": "Running Shoes",
"brand": "Nike",
"price": 12000
}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.
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
await idx.updateDocuments([{ id: '1', price: 11000 }]);
Response 200 OK
{ "indexed": 1 }Delete a single document by primary key.
SDK
await idx.deleteDocument('1');
Response 204 No Content
Delete multiple documents by a list of primary key values.
Request body
| Parameter | Type | Description |
|---|---|---|
| ids required | string[] | Array of document IDs to delete. Maximum 1,000. |
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
await idx.deleteBatch({ ids: ['1', '2', '3'] });
Response 200 OK
{ "deleted": 3 }Delete all documents matching a filter expression.
Request body
| Parameter | Type | Description |
|---|---|---|
| filter required | string | Filter expression. See the Filtering guide for syntax. |
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
await idx.deleteByFilter({ filter: "status = 'archived' AND price < 1000" });
Response 200 OK
{ "deleted": 50 }Limits
| Parameter | Type | Description |
|---|---|---|
| Batch size optional | constraint | Maximum 1,000 documents per upsert or delete-batch request. |
| Document size optional | constraint | Maximum 100 KB per document (serialized JSON). |
| Fields per document optional | constraint | Maximum 200 fields per document. |
| Delete-by-filter optional | constraint | Maximum 100,000 matching documents per request. |