HTTP API overview

The front door to the HTTP API section. Everything here applies to every endpoint; the per-resource pages document only what is specific to a route.

Verified against heather_server 0.4.1. Bodies are JSON (Content-Type: application/json); responses are JSON.

Source of truth: heather_server/src/main.rs (route table), heather_server/src/routes.rs and routes_db.rs (handlers), heather_server/src/models.rs (wire types).

Pages

A complete method+path index lives in the HTTP API reference.

The two route shapes

Every collection and algebra route exists twice:

The two are the same handler: the scoped shape resolves a database from the path and delegates to the legacy one (routes_db.rs wraps routes.rs). Behaviour, request bodies and responses are identical.

This section documents the scoped form. Each endpoint's heading carries the /db/{db}/... path, and the body names the legacy equivalent. To use the legacy form, drop the /db/{db} prefix; you get the default database.

The /vec/* routes are not mirrored under /db/{db}/ — they are stateless vector math and never touch a database.

Authentication

HTTP Basic on every route except /health, /healthz, /ready, /readyz (auth::is_unauth_route). A bearer token from POST /auth/token may be sent instead. See Manage users and authentication.

Authorization: Basic base64(user:password)
Authorization: Bearer <token>

Scope

A user is root or scoped to one database.

/auth/* is exempt from the scope check entirely — minting and revoking your own token is an identity operation, not a data one (auth::middleware).

/vec/* is root-only. The classifier admits a default-scoped user to the /collections, /algebra and /compose prefixes only; /vec is not on that list (heather_server/src/users.rs::is_authorized).

Errors

Failures return {"error": "<message>"} with one of:

Every scoped route returns 404 with database not found: {db} when the db segment names no mounted database. That case is not repeated per endpoint.

Create-on-write asymmetry

Note the asymmetry between reads and writes: write, read, attention, analyze, batch_analyze, documents/query and bulk_load call get_or_create_collection, so an unknown collection is created, not a 404. stats, config, locations, fingerprint, compress, documents and the algebra source collections require the collection to exist and return 404.

Server-side caps

Bodies are bounded by --max-body-size, but a small body can describe a large computation. Three caps bound the result; 0 disables one (heather_server/src/limits.rs).

See Configuration for every knob.