Skip to content
Development documentation for unreleased code on main. Behavior can change before a release. Latest release docs

HTTP API conventionsdev

The HTTP surface is plain JSON for bounded messages and NDJSON for streams. Collection names live in the path, and the request body uses the same field names as the protobuf messages.

Collections belong to a tenant. Search and update routes act in the caller’s own tenant, which is the default tenant t0 until requests carry credentials. Administration and snapshot routes may name another tenant under /tenants/{tenant}.

Method and path Purpose
GET / Binary version, full source commit hash, and CPU target.
GET /health Process liveness.
GET or POST /collections/{collection}/_search Search; URL request fields and optional POST JSON body, chunked NDJSON response.
POST /collections/{collection}/_update Bounded JSON update or unbounded NDJSON ingest.
GET /collections/{collection}/_schema Read the authored schema.
GET /collections/{collection}/_schema?view=resolved Read physical representations, bindings, and conservative schema coverage; HTTP only.
POST /collections/{collection}/_schema Set definitions or replace the schema; wait_for_replicas waits for followers.
GET /collections/_list (or POST) List collection names; GET /collections is a synonym.
POST /collections/_create (or PUT) Create a collection; body {"name": "...", "schema": {...}}; wait_for_replicas waits for followers.
POST /collections/_rename Rename one collection; body {"from":"old","to":"new"}. The destination must be free.
POST /collections/_swap Exchange two collection names in one catalog update; body {"a":"live","b":"staging"}.
POST /collections/_delete Delete a collection and its stored data; body {"name": "..."}.
GET /_stats Node statistics: service activity and memory by default; collections, files, segments, system and host opt in to costlier sections; format=prometheus renders Prometheus text. See Stats and monitoring.
GET /metrics The node’s Prometheus scrape: _stats rendered as Prometheus text, with collections and system on by default.
GET /collections/{collection}/_stats Statistics for one collection, in JSON or Prometheus text.
GET /collections/{collection}/_snapshot Pin the current snapshot for copying; see Replication.
GET /collections/{collection}/_snapshot/files/{name} One file of a pinned snapshot.
GET /tenants Tenants that own a collection.
/tenants/{tenant}/collections/... The administration and snapshot routes above (_list, _create, _delete, _rename, _swap, _schema, _stats, _snapshot) for a named tenant; GET /tenants/{tenant}/_stats covers that tenant.
GET /_replication/watch, POST /_replication/installed, GET /_replication/status Replication discovery, acknowledgments and status; see Replication.

Collection names occupy one URL path component. Names beginning with _ are reserved. Search and schema reads never create a missing collection; an update does by default unless --no-indexing.auto-create-collection is set.

_create installs the optional schema (same shape as a _schema set) before the collection becomes visible and returns {name, commit}. Schema writes return {schema, commit}; schema GET still returns the authored schema directly, suitable for posting back. Each token identifies the exact snapshot published by that operation. Search response envelopes include the token of the reader they used. See Collection lifecycle for deletion semantics under concurrent use.

Rename returns {from,to}; swap returns {a,b}. Both names must be distinct and in the route’s tenant. Requests admitted during a swap may see either binding per name; both names may briefly select the same collection. Missing names return 404, an occupied rename target 409, an in-progress transition 503, and read-only nodes or followers 403. The gRPC equivalents are luxir.Admin/RenameCollection and luxir.Admin/SwapCollections, with an optional tenant in each request.

GET / returns metadata compiled into the running binary, without collecting statistics or accessing Git at runtime:

{
"version": "0.1.0",
"source_commit": "0123456789abcdef0123456789abcdef01234567",
"cpu_target": "x86-64-v2"
}

source_commit identifies the checkout’s HEAD at build time; it does not describe uncommitted edits. It is "unknown" for source archives built without an explicit commit hash, or when the build could not read the checkout’s Git repository. luxir --version and the startup banner report the same version, commit, and CPU target. The root endpoint defaults to pretty JSON; use /?pretty=false for compact output.

Send bounded search, schema, and update messages as application/json. Send a document stream to _update as application/x-ndjson; one complete JSON value must end on each line.

GET search requests have no body. Search request fields may be written as typed URL parameters; on POST they overlay the parsed JSON body, with URL values winning field by field. See Searching for the whitelist and value grammars.

Search responses use application/x-ndjson with HTTP chunked transfer coding. Each normal line is one complete response batch. A small default-limit search usually has one line and therefore also parses as an ordinary JSON object. Use ?format=docs for document-per-line export without response envelopes; it emits row documents, so document_format columns or adaptive is rejected with it.

Explicit request ops return named results under response ops, preserving their hierarchy in every batch. Root query shorthand returns its implicit query’s found, docs, and sub-ops directly in the response envelope.

Every JSON body ends with a newline. ?pretty (bare, or ?pretty=true / ?pretty=false) is a URL-only, best-effort formatting hint that applies to every JSON body of the request, errors and ingest acknowledgements included. Build information, schema, collection list, and stats responses default to pretty; every other route defaults to compact. _stats?format=prometheus is text/plain; version=0.0.4 and ignores pretty. Indentation is two spaces but is not part of the contract. A pretty stream is sent as application/json, still chunked, with one pretty JSON text per batch separated by blank lines. It is not a single JSON document, though jq reads the sequence directly. Pretty is ignored for format=docs, whether selected by URL or body, which stays NDJSON.

The server applies backpressure to streaming producers. It does not buffer an unbounded request or response into one in-memory JSON value.

JSON field names and enums are lowercase snake_case. Values use natural JSON forms where their message type is known. For example, a kNN query vector is an array of numbers, a query can be a bare expression string, and {"match":{"title_t":"dune"}} is accepted field-name sugar. Document vector fields also accept bare number arrays. The schema interprets a number array as one vector and an array of number arrays as a multi-valued vector list.

JSON bodies are validated strictly, with positions reported for typos. Unknown URL parameters are ignored, allowing middleware metadata. Add ?explain=request to a query to return the canonical effective request, including URL overlays, without executing it; posting the result back executes the same operations. The echo expands shorthand into an explicit ops.q, so replaying it uses the named response shape.

The HTTP path collection is authoritative. Canonical echo may show it as "collection":"books" even when the original body omitted it.

The request and each operation wrapper accept a lowercase flags name array:

{"flags":["date_ms"],"ops":{"q":{"flags":["date_native"],"top_docs":{"query":"when_dt:2"}}}}

Operations inherit their parent’s options. Naming a date mode replaces the inherited date mode, including date_native to restore field-native literal units and numeric output. An empty array overrides nothing. The root shorthand accepts request flags beside query, filter, and other request controls. A bare expression op inherits flags; use an expr_op wrapper to override them.

Duplicate or conflicting names, unknown names, and reserved flags are request errors. Canonical echo and both explain modes emit names, including an explicit date_native override, rather than numeric masks. See date literal units and output. date_iso emits UTC strings, while date_ms and date_ns emit numeric dates in the named unit. This applies to documents, facets, groups, sort values and DATE metrics; the same output types are used over gRPC.

int64_str is request-level only. For example, "flags": ["date_ns", "int64_str"] renders JSON int64 and uint64 values as decimal strings only when they fall outside JavaScript’s safe integer range, -9007199254740991 through 9007199254740991 (Number.isSafeInteger). All other integers stay JSON numbers. The rule covers every integer in search responses, including fields, arrays, metrics, facets, group keys/ranks, counts, headers and profile metadata, in both envelope and docs formats. It does not apply to doubles. Clients using this flag must accept either a number or a string for a 64-bit value. Setting or clearing the flag on any operation is an error. Binary gRPC responses retain their integer types.

?explain=request is parse-and-serialize only. It returns the bare canonical request, including URL overlays, without acquiring readers or running semantic preparation. The entire response can be posted back as a request.

?explain=resolved returns the request together with field-binding notes. Using the author example:

POST /collections/authors/_search?explain=resolved
{
"query": {
"any_of": {
"field": "author_name",
"values": ["Neal Asher"]
}
},
"fields": ["id"]
}
{
"request": {
"collection": "authors",
"ops": {
"q": {
"top_docs": {
"query": {
"any_of": {
"field": "author_name",
"values": ["Neal Asher"]
}
},
"fields": ["id"]
}
}
}
},
"resolved_fields": ["q: author_name -> author_name__s"]
}

Replay the request member. Its field spellings stay as authored; resolved_fields contains contextual mappings to physical names where they differ, with repeated identical notes removed. These strings are diagnostics, not a serialized execution plan.

Resolved explain runs ordinary search preparation: it acquires readers, respects freshness, validates semantics, and may do dictionary, weight, and cache work. It requires a usable collection but does not execute result collection, calculators, or document emission, so it does not validate retrieval fully.

Every failure has one shape, wherever it appears:

{
"request_id": "q7",
"error": {
"kind": "invalid_request",
"code": "unknown_field",
"message": "Field not found: titel"
}
}

kind classifies the failure and determines its HTTP status. code is the stable machine key; message is human-readable detail. request_id is echoed when supplied in the body or as a URL parameter.

kind HTTP status Meaning
invalid_request 400 (405 for method_not_allowed) The request as written cannot be served.
not_found 404 The route or the collection does not exist.
already_exists 409 Creating a collection that already exists.
failed_precondition 403 (409 for commit_incarnation_mismatch) The node’s state forbids the operation, such as --read-only.
resource_exhausted 429 (413 for request_too_large) A size or memory ceiling was exceeded.
unavailable 503 The collection exists but cannot serve: it is being deleted or failed to load.
internal 500 A server-side failure the request did not cause.

A failure detected before output returns the kind’s HTTP status and this body. A wrong method on a known path returns 405 with an Allow header.

Once a chunked response has begun, its HTTP status cannot change, so a search that fails after output starts arrives with HTTP 200 as the final NDJSON line in the same shape, {"request_id": ..., "error": {...}, "warnings": [...]}, with no docs or ops. That final error invalidates every earlier batch line of the same request: a client that streamed more: true lines must discard them. Document-only format=docs has no error envelope: a failure before output becomes a normal error response, while a failure after documents were emitted aborts the body without its terminating chunk so the client sees truncation.

HTTP transport success and update success are separate. A syntactically valid update returns HTTP success with status: "partial" and per-document errors, each carrying the same error object; a request-level failure sets status: "error" and a top-level error. Clients must inspect the body. NDJSON ingest reports a request-level failure as a terminal response line after earlier group acknowledgements; no later records from that connection are accepted. URL EOF commits always return a commits map, even for a single collection, and collect every admitted collection outcome before responding. Entries contain commit, optional replicas, and error when that collection’s local commit failed. Replica wait outcomes (satisfied, timed_out, cancelled) retain the token and do not change local commit success. A local failure sets overall status: "error" and a top-level error, with HTTP 200, consistent with unary commit failures. See Indexing.

Search warnings are successful results with a bounded declared degradation. Use warnings[].code as the machine key and the message as diagnostic detail; warnings declared before a failure ride along with the error.

HTTP/1.1 keep-alive and request streaming are supported. A configured nonzero HTTP port currently binds all interfaces, and the server has no TLS, authentication, authorization, CORS policy, or tenant permission layer. Do not expose it directly to an untrusted network. See Operating Luxir.