API Reference

Returns 200 OK with body ok. Use this for load balancer health checks and container readiness probes.

Example

curl http://localhost:3000/health

Response

ok

Returns all Prometheus metrics in text exposition format (text/plain; version=0.0.4). See the monitoring guide for the full metric list and PromQL examples.

Example

curl http://localhost:3000/metrics

Appends rows to the namespace's Lance table. The vector dimension and the vector kind (single-vector or multivector) are inferred from the first upsert and enforced on subsequent calls. After a successful write, all cached query results for this namespace are invalidated.

Each row carries one of two vector payload shapes, depending on the namespace's kind:

• Single-vector namespaces: vector: float32[] — one dense vector of length dim.
• Multivector namespaces: vectors: float32[][] — a non-empty list of equal-length inner vectors. Used for ColBERT / ColPali / ColQwen2 late-interaction retrieval.

At most one of the two fields may be set on a row. The first row of the first upsert into a fresh namespace fixes the kind for its lifetime; payloads in the wrong shape return 400.

Request body

Response (200)

Examples

Single-vector upsert:

curl -X POST http://localhost:3000/ns/demo/upsert \
  -H 'Content-Type: application/json' \
  -d '{
    "rows": [
      {"id": 1, "vector": [1.0, 0.0, 0.0, 0.0], "text": "hello world"},
      {"id": 2, "vector": [0.0, 1.0, 0.0, 0.0]}
    ]
  }'

{"upserted": 2}

Multivector upsert:

curl -X POST http://localhost:3000/ns/demo-mv/upsert \
  -H 'Content-Type: application/json' \
  -d '{
    "rows": [
      {"id": 1, "vectors": [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0]]},
      {"id": 2, "vectors": [[0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0], [0.5, 0.5, 0.0, 0.0]]}
    ]
  }'

Errors

• 400 — invalid namespace name; vector dimension mismatch; payload shape mismatch (e.g. vector on a multivector namespace or vice versa); both vector and vectors set on the same row; empty inner sub-vector; mixed inner sub-vector dim within one row
• 500 — object-storage write failure (client gets generic error; full details logged server-side)

Queries the namespace through the cache-aside path. On a cache hit, the result is returned from RAM or NVMe with zero object-storage access. On a miss, the query runs against the configured backend via LanceDB and the result is cached.

Query modes

The query mode is determined by which fields are present. The vector field uses vector: float32[] for single-vector namespaces and vectors: float32[][] for multivector namespaces:

Request body

* At least one of vector, vectors, or text must be present. Setting both vector and vectors on the same request returns 400.

Response (200)

Examples

Single-vector search:

curl -X POST http://localhost:3000/ns/demo/query \
  -H 'Content-Type: application/json' \
  -d '{"vector": [1.0, 0.0, 0.0, 0.0], "k": 5}'

Multivector search:

curl -X POST http://localhost:3000/ns/demo-mv/query \
  -H 'Content-Type: application/json' \
  -d '{"vectors": [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0]], "k": 5}'

Full-text search:

curl -X POST http://localhost:3000/ns/demo/query \
  -H 'Content-Type: application/json' \
  -d '{"text": "search query terms", "k": 10}'

Hybrid search (single-vector + FTS):

curl -X POST http://localhost:3000/ns/demo/query \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [1.0, 0.0, 0.0, 0.0],
    "text": "search terms",
    "k": 10,
    "nprobes": 40
  }'

Returns rows in ingest order for "recent content" flows (landing pages, new-uploads feeds, back-catalogue browsing). Results are ordered by the reserved _ingested_at system column (microsecond server-side timestamp, set at first write and never mutated).

This endpoint intentionally bypasses the foyer cache. Pagination tails would push hot query results out of RAM and NVMe without an offsetting hit rate, so /list goes directly to the Lance dataset.

Query parameters

Response (200)

Status codes

Examples

First page, newest first:

curl 'http://localhost:3000/ns/demo/list?limit=50'

Next page via cursor:

curl 'http://localhost:3000/ns/demo/list?limit=50&cursor=0006012a9abb9c800000000000000007'

Removes every object under the namespace's prefix and evicts all cached query results. This is irreversible.

Response (200)

Example

curl -X DELETE http://localhost:3000/ns/demo

{"objects_deleted": 12}

Accepts a list of queries and runs them in a background task to populate the cache. Returns 202 Accepted immediately. Useful for warming the cache after a deployment or before expected traffic.

Request body

Response (202)

Example

curl -X POST http://localhost:3000/ns/demo/warmup \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": [
      {"vector": [1.0, 0.0, 0.0, 0.0], "k": 5},
      {"vector": [0.0, 1.0, 0.0, 0.0], "k": 5}
    ]
  }'

{"queued": 2}

Builds an IVF_PQ (Inverted File with Product Quantisation) index on the namespace's vector column. Returns 202 Accepted and builds in the background. Building an index dramatically reduces cold query latency (25x speedup on AWS S3).

Request body

Response (202)

{"status": "index build queued"}

Example

curl -X POST http://localhost:3000/ns/demo/index \
  -H 'Content-Type: application/json' \
  -d '{"kind": "ivf_pq"}'

Builds a BM25 full-text search index on the namespace's text column. Required before FTS or hybrid queries will return results. Returns 202 Accepted.

Request body

No request body required.

Response (202)

{"status": "fts index build queued"}

Example

curl -X POST http://localhost:3000/ns/demo/fts-index

Builds a BTree scalar index on the reserved _ingested_at column. With the index in place, /list cursor pages do an index range scan instead of a full-fragment scan, and the leading ORDER BY _ingested_at short-circuits the in-memory sort step. Returns 202 Accepted.

Request body

No request body required. v1 hardcodes the column to _ingested_at — the same constraint /list puts on order_by.

Response (202)

{"status": "scalar index build queued"}

Example

curl -X POST http://localhost:3000/ns/demo/scalar-index

Merges small Lance data fragments into fewer, larger files to reduce object-storage round-trips on cold queries. Returns 202 Accepted. Also invalidates the cache for this namespace, since file offsets change after compaction.

Request body

No request body required.

Response (202)

{"status": "compaction queued"}

Example

curl -X POST http://localhost:3000/ns/demo/compact