REST API

JSON over HTTP, on port 6900 by default. Request bodies must be sent with content-type: application/json (except snapshot uploads), and may not contain unknown fields. With API keys configured, every route except / and /health needs one, in Authorization: Bearer <key> or x-api-key: <key>: read routes take any key, write routes a read-write key. See security.

Server

curl localhost:6900/health
curl localhost:6900/info

{"status":"ok","version":"0.1.0"}
{"collections":0,"points":0,"snapshots_enabled":true,"storage":"file","version":"0.1.0"}

Collections

A CollectionInfo is {"name", "dimension", "metric", "index", "quantization"?, "on_disk"?, "vectors"?, "sparse_vectors"?, "count", "tombstones", "field_indexes"}, where index is {"type": "hnsw", "m", "ef_construction", "ef_search", "seed"}, {"type": "flat"} or {"type": "kd_tree", "balance_factor"}, and quantization is "scalar" or left out. vectors maps names to {"dimension", "metric", "index", "quantization"?, "on_disk"?}, and sparse_vectors names to {"modifier"?: "idf"}; both, and on_disk, are left out when unset. In PATCH, index is merged into the current settings as a JSON Merge Patch. See collections & points, indexes & metrics and field indexes.

Aliases

An alias works in place of a collection name on every /collections/{name}/… route except DELETE and rename. See aliases.

Points

Points whose id is lookup, count, scroll, facet, metadata or delete cannot be read with GET /points/{id}, which those routes shadow; use points/lookup. A point is {"id", "vector", "vectors"?, "sparse_vectors"?, "metadata"}; vectors maps names to dense vectors and sparse_vectors names to {"indices", "values"}. metadata is left out when the point has none, and the vectors when with_vectors is false. Lookups and deletes take at most 10,000 ids, and limit is at most 10,000. See data operations and listing points.

curl -X POST localhost:6900/collections -H 'content-type: application/json' \
  -d '{"name": "places", "dimension": 2, "metric": "euclidean"}' > /dev/null
curl -X POST localhost:6900/collections/places/points -H 'content-type: application/json' \
  -d '{"points": [{"id": "brussels", "vector": [4.35, 50.85]}, {"id": "lille", "vector": [3.06, 50.63]}]}'
curl -X POST localhost:6900/collections/places/points/lookup -H 'content-type: application/json' \
  -d '{"ids": ["lille", "paris", "brussels"], "with_vectors": false}'

{"ids":["brussels","lille"],"upserted":2}
{"points":[{"id":"lille"},{"id":"brussels"}]}

Search

A hit is {"id", "distance", "metadata"?, "vector"?, "vectors"?, "sparse_vectors"?}, closest first; for a sparse search, distance is the negated score. A scored hit has a score instead, highest first. using names a named vector; sparse needs it. See searching.

curl -X POST localhost:6900/collections/places/search -H 'content-type: application/json' \
  -d '{"vector": [5.5, 50.5], "k": 1}'

{"results":[{"distance":1.2020812034606934,"id":"brussels"}]}

Snapshots

A SnapshotInfo is {"format_version", "id", "collection", "created_at_ms", "quiver_version", "config": {"dimension", "metric", "index", "quantization"?, "on_disk"?, "vectors"?, "sparse_vectors"?}, "points", "data_bytes", "data_sha256", "archive_bytes", "field_indexes"?}. See snapshots & backups.

Errors

Every error has the same shape:

{"error": {"code": "not_found", "message": "collection `nope` not found"}}

A route that exists but not for that method answers 405 with an empty body.

curl localhost:6900/collections/nope
curl -X POST localhost:6900/collections/places/search -H 'content-type: application/json' -d '{"vector": [1.0]}'
curl -X POST localhost:6900/collections/places/search -H 'content-type: application/json' -d '{"vector": [1.0, 2.0], "top_k": 3}'

{"error":{"code":"not_found","message":"collection `nope` not found"}}
{"error":{"code":"dimension_mismatch","message":"dimension mismatch: expected 2, got 1"}}
{"error":{"code":"invalid_body","message":"Failed to deserialize the JSON body into the target type: top_k: unknown field `top_k`, expected one of `vector`, `id`, `sparse`, `using`, `k`, `filter`, `ef`, `max_distance`, `with_vectors`, `with_metadata` at line 1 column 30"}}

Limits

--cors allows cross-origin requests from any origin; leave it off unless a browser application on another origin needs the API.