Maintenance Operations

The maintenance endpoints allow you to delete items, rebuild indexes, and optimize graphs to maintain index health over time.

Delete Items

Remove items from an index by their external IDs.
POST /delete

Request Body

{
  "index_name": "my_index",
  "external_ids": ["item_001", "item_002", "item_003"],
  "return_not_found": false
}
FieldTypeRequiredDefaultDescription
index_namestringYesName of the index
external_idsstring[]YesList of external IDs to delete
return_not_foundbooleanNofalseWhether to return IDs not found in the index

Response

{
  "deleted_count": 2,
  "not_found": ["item_003"]
}
FieldTypeDescription
deleted_countintegerNumber of items successfully deleted
not_foundstring[] | nullIDs that were not found (only if return_not_found=true)

Errors

StatusCondition
400Empty external_ids list or deletion failed
404Index not found

Rebuild Index

Perform a compact rebuild of an index. This creates a new HNSW graph from scratch using only the live (non-deleted) vectors, merging the main and delta segments.
POST /rebuild

Request Body

{
  "index_name": "my_index",
  "params": {
    "M": 48,
    "ef_construction": 1024,
    "ef_search": 512,
    "rng_seed": 0
  }
}
FieldTypeRequiredDefaultDescription
index_namestringYesName of the index
paramsobjectNoexistingOptional HNSW parameters for the rebuild

Response

{
  "success": true,
  "message": "Index 'my_index' rebuilt and compacted",
  "index_name": "my_index"
}

When to Rebuild

Rebuild the index when:
  • You’ve deleted a significant number of items and the graph is fragmented
  • The delta segment has grown large after many insert/upsert operations
  • You want to change HNSW parameters for better recall or performance
  • needs_rebuild returns true from the status endpoint

Errors

StatusCondition
400Rebuild failed
404Index not found

Optimize Graph

Optimize the HNSW graph in place. This is a lighter-weight alternative to a full rebuild that can restore some search performance.
POST /optimize

Request Body

{
  "index_name": "my_index"
}

Response

{
  "success": true,
  "message": "Graph optimized for index 'my_index'",
  "index_name": "my_index"
}

Optimize vs. Rebuild

AspectOptimizeRebuild
SpeedFastSlow
Quality improvementModerateMaximum
Merges delta segmentNoYes
Can change HNSW paramsNoYes
Recommended forLight maintenanceHeavy modifications

Errors

StatusCondition
400Optimization failed
404Index not found