​
Index Management

The index management endpoints allow you to create, list, load, check status, and delete indexes on the brinicle server.

​
Create Index

Create a new vector index with specified parameters. 
POST /indexes

​
Request Body

{
  "index_name": "my_index",
  "dim": 384,
  "delta_ratio": 0.10,
  "params": {
    "M": 48,
    "ef_construction": 1024,
    "ef_search": 512,
    "rng_seed": 0
  }
}
FieldTypeRequiredDefaultDescription
index_namestringYes—Unique name (alphanumeric + underscore, max 64 chars)
dimintegerYes—Vector dimensionality (>= 1)
delta_ratiofloatNo0.10Delta index ratio (0.0 to 0.5)
paramsobjectNodefaultsHNSW parameters
params.MintegerNo16Bi-directional links per node
params.ef_constructionintegerNo200Build-time search width
params.ef_searchintegerNo64Query-time search width
params.rng_seedintegerNo0RNG seed

​
Response

{
  "success": true,
  "message": "Index 'my_index' created successfully",
  "index_name": "my_index"
}

​
Errors

StatusCondition
409Index with this name already exists
400Invalid parameters or creation failed

​
List Indexes

Get a list of all loaded indexes. 
GET /indexes

​
Response

{
  "indexes": ["my_index", "another_index"],
  "count": 2
}

​
Get Index Status

Check the status of a specific index. 
GET /indexes/{index_name}/status

​
Response

{
  "index_name": "my_index",
  "dim": 384,
  "has_index": true,
  "needs_rebuild": false
}
FieldTypeDescription
index_namestringName of the index
dimintegerVector dimensionality
has_indexbooleanWhether an index exists (data has been ingested and finalized)
needs_rebuildbooleanWhether the index would benefit from a compact rebuild

​
Errors

StatusCondition
404Index not found

​
Load Index

Load an existing index from disk into memory. Use this when the server restarts and you need to load indexes that were previously created. 
POST /indexes/load

​
Request Body

{
  "index_name": "my_index"
}

​
Response

{
  "success": true,
  "message": "Index 'my_index' created successfully",
  "index_name": "my_index"
}
The server stores index data in /app/data/ by default. When you load an index, the dimension is read from the index files on disk, so you don’t need to specify it.

​
Delete Index

Close or destroy an index. 
DELETE /indexes/{index_name}?destroy=false

​
Query Parameters

ParameterTypeDefaultDescription
destroybooleanfalseIf true, permanently delete index files from disk

​
Response

{
  "success": true,
  "message": "Index 'my_index' closed and removed",
  "index_name": "my_index"
}
When destroy=false (default), the index is closed and removed from memory but the data files remain on disk. When destroy=true, all index files are permanently deleted.

​
Errors

StatusCondition
404Index not found
400Failed to close or destroy the index