DocumentationReference

HTTP API reference

The HTTP API is documented one page per resource group under docs/api/. Start at the API overview for the conventions that apply to every route: the legacy vs /db/{db} dual-route shapes, authentication, scope, the error format, and the server-side caps.

This page is the index: every method and path the engine serves, linked to the endpoint that documents it.

Pages

Page	Covers
Overview	conventions, auth, scope, errors, caps
Ops	`/health`, `/healthz`, `/ready`, `/readyz`
Auth	session tokens
Databases	`/db` management
Collections	create, list, drop, stats, config, locations, compress, fingerprint
Writes	`write`, `bulk_load`
Reads	`read`, `attention`, `analyze`
Documents	document storage and similarity search
Algebra	algebra over collections, `compose/read`
Vectors	stateless `/vec/*` math
Audit	the access log
Dream	on-demand consolidation

Route table

45 endpoints, verified against heather_server 0.4.1. Collection and algebra routes exist in two shapes; both are listed, and both link to the one endpoint that documents them. The /db/{db} shape addresses any database, the legacy shape addresses default.

Source of truth: heather_server/src/main.rs.

Ops

Route	Legacy form
GET /health	—
GET /healthz	—
GET /ready	—
GET /readyz	—

Auth

Route	Legacy form
POST /auth/token	—
POST /auth/token/revoke	—

Databases

Route	Legacy form
GET /db	—
POST /db	—
GET /db/{db}	—
DELETE /db/{db}	—

Dream

Route	Legacy form
POST /db/{db}/dream	—

Audit

Route	Legacy form
GET /db/{db}/audit	—

Collections

Route	Legacy form
POST /db/{db}/collections	POST /collections
GET /db/{db}/collections	GET /collections
DELETE /db/{db}/collections/{name}	DELETE /collections/{name}
GET /db/{db}/collections/{name}/stats	GET /collections/{name}/stats
GET /db/{db}/collections/{name}/config	GET /collections/{name}/config
GET /db/{db}/collections/{name}/locations	GET /collections/{name}/locations
POST /db/{db}/collections/{name}/compress	POST /collections/{name}/compress
GET /db/{db}/collections/{name}/fingerprint	GET /collections/{name}/fingerprint

Writes

Route	Legacy form
POST /db/{db}/collections/{name}/write	POST /collections/{name}/write
POST /db/{db}/collections/{name}/bulk_load	POST /collections/{name}/bulk_load

Reads

Route	Legacy form
POST /db/{db}/collections/{name}/read	POST /collections/{name}/read
POST /db/{db}/collections/{name}/attention	POST /collections/{name}/attention
POST /db/{db}/collections/{name}/attention/mdl	POST /collections/{name}/attention/mdl
POST /db/{db}/collections/{name}/attention/calibrate	POST /collections/{name}/attention/calibrate
POST /db/{db}/collections/{name}/analyze	POST /collections/{name}/analyze
POST /db/{db}/collections/{name}/batch_analyze	POST /collections/{name}/batch_analyze

Documents

Route	Legacy form
GET /db/{db}/collections/{name}/documents	GET /collections/{name}/documents
GET /db/{db}/collections/{name}/documents/{doc_id}	GET /collections/{name}/documents/{doc_id}
DELETE /db/{db}/collections/{name}/documents/{doc_id}	DELETE /collections/{name}/documents/{doc_id}
POST /db/{db}/collections/{name}/documents/query	POST /collections/{name}/documents/query

Algebra

Route	Legacy form
POST /db/{db}/algebra/add	POST /algebra/add
POST /db/{db}/algebra/sub	POST /algebra/sub
POST /db/{db}/algebra/bind	POST /algebra/bind
POST /db/{db}/algebra/intersect	POST /algebra/intersect
POST /db/{db}/algebra/scale	POST /algebra/scale
POST /db/{db}/algebra/permute	POST /algebra/permute
POST /db/{db}/algebra/unbind	POST /algebra/unbind
POST /db/{db}/compose/read	POST /compose/read

Vectors

Route	Legacy form
POST /vec/bind	—
POST /vec/unbind	—
POST /vec/bundle	—
POST /vec/pow	—
POST /vec/rotate	—

Edit this page on GitHub