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

Inserts or updates rows in the namespace's Lance table, keyed by id. 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.

Upsert is latest-write-wins: re-sending a row whose id already exists replaces the stored row in full (vector, text, attribute values, and the _ingested_at timestamp), so replaying a request and updating a document are both safe. Replacing in full means a row re-sent without its attributes comes back without them. A row with a new id is inserted. Because _ingested_at is rewritten on update, it reflects the most recent write to a row rather than its first insert. Duplicate ids within a single request are rejected with 400.

The first write to a namespace builds a BTree index on id automatically, so the per-batch merge that matches incoming ids against stored rows uses the index instead of scanning every data file. For a large first load, see the recommended load/compact/index recipe in the README; for namespaces created before this behaviour existed, build the index once via POST /ns/{namespace}/scalar-index with {"column": "id"}.

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; an undeclared attribute name, a value whose type does not match its declared column, or an attribute value that is not a scalar
• 500 — object-storage write failure (client gets generic error; full details logged server-side)

The bulk first-load path. The body is an Arrow IPC stream, not JSON: binary and columnar, so embeddings avoid JSON's ~3x decimal-text inflation, and the route is not bound by FIRNFLOW_MAX_BODY_BYTES (a whole corpus can stream in one request). The entire stream is appended in a single Lance commit, which is what keeps throughput flat on a large load where many small /upsert commits would not.

Insert-only. Rows are appended, not merged: a repeated id creates a second row. Use /import for first-loads or known-new ids, and /upsert for idempotent updates. Build indexes after the load (see the README "Loading data at scale" recipe).

Request

Content-Type: application/vnd.apache.arrow.stream (application/octet-stream is also accepted). The stream's Arrow schema must carry:

• id — UInt64, non-null.
• exactly one of vector (FixedSizeList<Float32, dim>, single-vector) or vectors (List<FixedSizeList<Float32, dim>>, multivector). The FixedSizeList child field must be named item (the default for e.g. PyArrow).
• optional text — Utf8.
• optionally, any of the metadata columns declared on this namespace through POST /ns/{namespace}/attributes, each under its declared name and Arrow type: string as Utf8, int as Int64, float as Float64, bool as Boolean. A declared column the stream leaves out is null for every row it writes. Types must match exactly: unlike the JSON path, which widens an integer into a float column because JSON has a single number type, Arrow carries the type the caller chose, so an Int64 array for a float column is a 400 rather than a conversion.
• _ingested_at must not be present; the server sets it.
• any other column is rejected — a misspelled name is a 400, not silently dropped. Vector floats must be non-null (no null child values inside a vector or sub-vector), and multivector rows must have at least one sub-vector.

On a fresh namespace the stream fixes the vector kind and dimension; on an existing one they must match. Because declaring a column needs a namespace that already exists, a namespace's very first write cannot carry attribute values: the order is import, declare, then import again with values, the same as on the JSON path. Schema problems are rejected with 400 before any work starts; row-level problems (null id, empty multivector row) and a truncated/malformed stream surface as a failed operation after the 202.

Response (202)

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "import",
  "namespace": "demo",
  "status": "running"
}

Poll GET /operations/{operation_id} for completion. Tuning: FIRNFLOW_IMPORT_MAX_BYTES caps a single import body spooled to disk (default 8 GiB; 0 disables, returns 413 when exceeded), and FIRNFLOW_IMPORT_TMP_DIR sets the spool directory.

Example

# write an Arrow IPC stream file (e.g. with pyarrow's RecordBatchStreamWriter), then:
curl -X POST http://localhost:3000/ns/demo/import \
     -H 'Content-Type: application/vnd.apache.arrow.stream' \
     --data-binary @rows.arrows

Errors

• 400 — body is not a valid Arrow IPC stream, or the schema is missing/extra/mistyped (see Request)
• 413 — body exceeds FIRNFLOW_IMPORT_MAX_BYTES
• 415 — wrong Content-Type

Declares the scalar metadata columns a namespace carries. Out of the box a query filter can only reference id and _ingested_at; declared columns are the caller's own fields (section, tenant, language, category, status) and are what makes filtered retrieval useful.

Columns are declared rather than inferred from the rows that carry them. A column whose first value is 2024 looks like an integer until someone sends 2024.5, and a column whose first value is absent has no type at all, so inference defers a schema decision to a write that fails later on data that looks fine.

The namespace must already exist, the same precondition the index builders have: a namespace is created by its first write, so the order is write, declare, then write again with values. Unlike the index builders this endpoint is synchronous, because adding the columns is a single metadata commit that writes nulls into existing rows rather than a pass over the data.

Request body

A namespace holds at most 32 attribute columns.

Response (200)

Example

curl -X POST http://localhost:3000/ns/demo/attributes \
     -H 'Content-Type: application/json' \
     -d '{"attributes": [
           {"name": "section", "type": "string"},
           {"name": "year",    "type": "int"},
           {"name": "archived","type": "bool"}
         ]}'

{
  "attributes": [
    {"name": "section", "type": "string"},
    {"name": "year", "type": "int"},
    {"name": "archived", "type": "bool"}
  ]
}

Status codes

Queries the namespace through the cache-aside path. On a cache hit, the result is returned from RAM or NVMe without re-running the search; once the namespace handle is warm a hit makes no object-storage access, though the first query to a namespace in a process reads the table manifest once to form the version-based cache key. 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.

Semantic cache

An optional semantic_cache block lets the server reuse a previous query's result when the new query vector is very close to a recent one against the same namespace generation. The exact result cache is still consulted first; only when it misses does the semantic layer get a chance to short-circuit. Eligible requests are single-vector only in v1; multivector, FTS, hybrid, and filtered requests with the field enabled return 400.

Behaviour:

• The semantic_cache block does not change the exact-cache key. Toggling enabled on and off does not split otherwise-identical entries.
• k, nprobes, and include_vector must match between the incoming request and the cached candidate; mismatches are skipped. A vector-light cached result is never used to answer a request that wants vectors back, or vice versa.
• Any committed change drops the semantic layer alongside the exact cache: writes, deletes, compactions, and index builds. An index build invalidates too, because it is a Lance commit that advances the table version the cache keys on, even though the rows are unchanged.
• Behaviour is observable via three Prometheus counters: firnflow_semantic_cache_hits_total{namespace}, firnflow_semantic_cache_misses_total{namespace}, and firnflow_semantic_cache_rejections_total{namespace, reason} (with bounded reason labels: unsupported_query_shape, empty_index).

curl -X POST http://localhost:3000/ns/demo/query \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.10, 0.21, 0.29, 0.40],
    "k": 10,
    "semantic_cache": {"enabled": true, "min_similarity": 0.995}
  }'

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}'

Metadata-filtered 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": 20,
    "filter": "section = '"'"'warnings'"'"' AND year >= 2024"
  }'

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 of the most recent write; re-upserting a row advances it).

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'

Returns operational metadata for a namespace: its vector shape, live row count, fragment count, which index kinds are built, and the current Lance table version. Useful for dashboards and for deciding when to compact or build an index, without querying the data or inspecting raw objects.

Like /list, this bypasses the foyer cache; it is namespace state, not a query result. It never creates a table, so a namespace that has never been written returns 404.

Response (200)

Status codes

Example

curl http://localhost:3000/ns/demo

{
  "namespace": "demo",
  "kind": "single",
  "vector_dim": 1536,
  "row_count": 100000,
  "fragment_count": 3,
  "has_vector_index": true,
  "has_fts_index": false,
  "has_scalar_index": false,
  "table_version": 42,
  "attributes": [
    {"name": "section", "type": "string"},
    {"name": "year", "type": "int"}
  ]
}

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. Query objects use the same schema as /query; include semantic_cache: {"enabled": true} on eligible single-vector warmup queries if you also want to seed the semantic sidecar.

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}
    ]
  }'

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "warmup",
  "namespace": "demo",
  "status": "running",
  "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)

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "index",
  "namespace": "demo",
  "status": "running"
}

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 any query carrying text will run at all. Without it, FTS and hybrid queries on a namespace that has rows return 400 rather than an empty result set. Returns 202 Accepted.

Full-text queries still find rows written after the index was built, so there is no need to rebuild after every write. The index itself does not cover them. Lance scans the data files it does not yet cover and merges those scores in with the indexed ones. Compaction folds the stragglers in, and until it does they cost a scan, so a namespace under steady writes still wants periodic POST /ns/{namespace}/compact for latency. The BTree on id behaves differently: there, rows written after the build are simply not covered until a compaction folds them in.

Request body

No request body required.

Response (202)

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "fts_index",
  "namespace": "demo",
  "status": "running"
}

Example

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

Builds a BTree scalar index on a namespace column. On _ingested_at (the default) the index lets /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. On id it speeds up the per-batch merge-insert lookup the write path runs (see /upsert). Returns 202 Accepted.

Request body

Optional. {"column": "id"} indexes the row id; an empty body defaults to _ingested_at. Valid columns are id, _ingested_at, and any metadata column the namespace has declared; any other value returns 400 before the background build starts. On a metadata column the index is what stops a filter over it scanning the matching rows, so it is worth building on any column a workload filters by regularly. A namespace's first write already builds the id index automatically, so this is the maintenance path for namespaces created before that behaviour existed.

Response (202)

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "scalar_index",
  "namespace": "demo",
  "status": "running"
}

Example

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

# index the row id (write-path maintenance path)
curl -X POST http://localhost:3000/ns/demo/scalar-index \
     -H 'Content-Type: application/json' \
     -d '{"column": "id"}'

# index a declared metadata column so filters over it use the index
curl -X POST http://localhost:3000/ns/demo/scalar-index \
     -H 'Content-Type: application/json' \
     -d '{"column": "section"}'

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)

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "compact",
  "namespace": "demo",
  "status": "running"
}

Example

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

Returns the current state of background work started by an async endpoint (warmup, index, fts-index, scalar-index, compact). Each of those returns an operation_id in its 202; poll this endpoint to wait for completion instead of inferring it from metrics.

Records are kept in memory and bounded: the most recent completed operations are retained and running operations are never evicted, so an unknown or long-since-completed id returns 404.

Response (200)

Status codes

Example

curl http://localhost:3000/operations/op_018f3a2b-7c4d-7e1f-9abc-1234567890ab

{
  "operation_id": "op_018f3a2b-7c4d-7e1f-9abc-1234567890ab",
  "kind": "scalar_index",
  "namespace": "demo",
  "status": "succeeded",
  "started_at_ms": 1779580800123,
  "finished_at_ms": 1779580802456,
  "error": null
}