Valori LogoValori
POST/v1/namespaces/{name}/indexREAD / WRITE

Configure a collection's index

Build, replace, or drop the ANN index for one collection. Asynchronous.

One endpoint, three effects — there is no separate "change" operation in the contract, it's the same request shape with a different type:

  • Create or replace: send type: "hnsw" | "ivf" | "bq". If an index already exists, the current one keeps serving searches while the new one builds in the background.
  • Drop: send type: null. Reverts the collection to exact (brute-force) search — no dedicated ANN structure.

A build is asynchronous: 202 means the build started, and the response carries the building generation. Poll Collection index state until status settles.

Only hnsw, ivf, and bq are buildable per collection — narrower than the project-wide rebuild's brute/auto options, which are project-level selections, not per-collection ANN structures. Sending one of those here is a 400 invalid_index error, not silently accepted.

Parameters

namestringrequired

Collection name (path parameter).

Request body

typestringoptional

"hnsw", "ivf", "bq", or null to drop the index. Omitting the field entirely behaves the same as null.

parametersobjectoptional

Optional tuning overrides. Unknown keys are ignored, not rejected — the contract only names the five keys the build actually reads.

parameters.mintegeroptional
HNSW: neighbours per node.
parameters.ef_constructionintegeroptional
HNSW: candidate-list size during construction.
parameters.ef_searchintegeroptional
HNSW: candidate-list size during search.
parameters.n_listintegeroptional
IVF: centroid count. Omit to auto-scale to max(16, sqrt(N)).
parameters.n_probeintegeroptional
IVF: probe count. Omit to auto-scale to max(1, sqrt(n_list)).

Response fields

Same shape as Collection index state — see that page's response fields.

Errors

StatuscodeMeaning
400invalid_indextype isn't one of hnsw/ivf/bq/null — e.g. sending brute or auto, which are project-level, not per-collection.
401unauthorizedMissing or invalid API key.
403forbiddenThe key's scope doesn't include read_write.
404collection_not_foundNo such collection.
409conflictA build is already in progress for this collection.
501not_implementedANN index management is unavailable on this node.

Related endpoints

POST /v1/namespaces/{name}/index
curl -X POST "https://app.valori.systems/v1/namespaces/documents/index" \
  -H "Authorization: Bearer vlk_your_project_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hnsw",
    "parameters": { "m": 16, "ef_construction": 200 }
  }'
202
{
  "collection": "documents",
  "desired_type": "hnsw",
  "active_type": "none",
  "status": "building",
  "building_generation": 2,
  "active_generation": null
}