Skip to content

Latest commit

 

History

History
113 lines (86 loc) · 3.22 KB

api-reference.md

File metadata and controls

113 lines (86 loc) · 3.22 KB

HTTP API Reference

The shardlake serve command exposes a minimal JSON HTTP API built on axum.

Base URL: http://<bind-address> (default http://0.0.0.0:8080)

All request bodies must be Content-Type: application/json. All responses are JSON.

GET /health

Returns the current health status and the index version being served.

Response

{
  "status": "ok",
  "index_version": "idx-v1"
}
Field Type Description
status string Always "ok" when the server is running
index_version string Version string from the loaded manifest

Example

curl -s http://localhost:8080/health

POST /query

Performs approximate nearest-neighbour (ANN) search and returns the top-k most similar vector ids with their scores.

Request body

{
  "vector": [0.1, 0.2, 0.3],
  "k": 10,
  "nprobe": 3
}
Field Type Required Description
vector float[] Yes Query vector. Must have the same number of dimensions as the index.
k integer Yes Number of results to return. Must be ≥ 1.
nprobe integer No Number of shards to probe. Defaults to the value set via --nprobe when the server was started. Higher values improve recall at the cost of latency.

Success response — 200 OK

{
  "results": [
    {
      "id": 42,
      "score": 0.0031,
      "metadata": {"label": "dog"}
    },
    {
      "id": 7,
      "score": 0.0157,
      "metadata": null
    }
  ],
  "index_version": "idx-v1"
}
Field Type Description
results array Ordered list of nearest neighbours, best match first
results[].id integer Numeric vector id as provided at ingest time
results[].score float Distance score. Lower is better for cosine and euclidean; lower is also better for inner_product (scores are negated internally).
results[].metadata object or null Metadata attached to this vector at ingest time, or null if none was provided
index_version string Index version used to serve this query

Error responses

Status Body Cause
400 Bad Request {"error": "k must be > 0"} k field is 0
400 Bad Request {"error": "query vector dimensions do not match the index"} Query vector length differs from the manifest dims
500 Internal Server Error {"error": "<message>"} Internal search failure

Example

curl -s -X POST http://localhost:8080/query \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.5, 0.3, 0.8, 0.1],
    "k": 5,
    "nprobe": 3
  }' | python3 -m json.tool

Notes on scoring

  • Cosine distance: score = 1 - cosine_similarity. Range [0, 2]; 0 means identical direction.
  • Euclidean distance: score = sqrt(sum((a_i - b_i)^2)). Range [0, ∞).
  • Inner product: score = -dot(a, b). Negated so that lower is always better; the most similar vector has the most negative raw dot product but the smallest (most negative → closest to zero) reported score.

In all cases, results are sorted ascending by score (best match first).