hms-server reference¶
One engine store per tenant. The /api/v1 contract is stable: see docs/server/versioning.md. Errors are RFC 9457 problem details.
Version 0.6.1 of the OpenAPI document the server publishes.
- Server:
/
Operations¶
admin¶
POST /api/v1/admin/keys/reload¶
Re-read --keys-file. Needs an all-tenant admin key.
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | KeysReloaded |
default | Error (RFC 9457 problem details) | Problem |
GET /api/v1/admin/tenants¶
Tenants with a store on disk. Needs an all-tenant admin key.
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Tenants |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/admin/tls/reload¶
Re-read --tls-cert and --tls-key. Needs an all-tenant admin key.
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | TlsReloaded |
default | Error (RFC 9457 problem details) | Problem |
index¶
GET /api/v1/compaction¶
Compaction status and schedule for the tenant.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | CompactionStatusBody |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/compaction¶
Compact the tenant's store now.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | CompactionRun |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/index/maintain¶
Train the tenant's document index over stored embeddings.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Request body
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Maintained |
default | Error (RFC 9457 problem details) | Problem |
documents¶
GET /api/v1/documents¶
List document ids and metadata, paginated by id cursor.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
limit | query | integer | Page size, 1..=1000 (default 100). | |
after | query | string | The next_cursor of the previous page. |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | DocumentPage |
304 | ETag matched If-None-Match | |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/documents¶
Store or replace one document.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: DocIn
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Added |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/documents/batch¶
Store or replace up to --max-batch documents in one atomic commit.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: array of DocIn
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Added |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/documents/stream¶
Bulk ingest newline-delimited documents, committed in batches; not atomic across batches.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Request body (required)
Content type application/x-ndjson: string (binary)
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | StreamResult |
default | Error (RFC 9457 problem details) | Problem |
DELETE /api/v1/documents/{id}¶
Delete a document by id (percent-encoded).
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
id | path | string | required | Document id, percent-encoded. |
purge | query | boolean | true also rewrites the journal and scrubs what the deleted document left behind. |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Deleted |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/query¶
Nearest documents to a vector, best first, with exact cosine scores.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Request body (required)
Content type application/json: QueryIn
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Matches |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/search¶
Text search: document ids and scores, best first (BM25, or the on-device model stages when configured); stored text and metadata on request.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Request body (required)
Content type application/json: SearchIn
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | SearchHits |
default | Error (RFC 9457 problem details) | Problem |
GET /api/v1/stats¶
Document and vector counts and storage use for the tenant.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
If-None-Match | header | string | Return 304 when the ETag still matches. |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Stats |
304 | ETag matched If-None-Match | |
default | Error (RFC 9457 problem details) | Problem |
memory¶
POST /api/v1/memory/applyForgetting¶
Apply the configured forgetting policy. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/consolidate¶
Run the configured consolidation policy. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/explain¶
Recall with the evidence behind each result and its supersession chain. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/forget¶
Forget facts by id, source or scope. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/get¶
Fetch one fact by id. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/history¶
A fact's version and supersession history. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/recall¶
Retrieve facts for a query, honoring validity time and supersession. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/remember¶
Store one fact or an array of facts with validity time, source and supersession. See docs/memory-api.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
Idempotency-Key | header | string | Replays the recorded response for a retried request (1..=128 visible ASCII characters). |
Request body (required)
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | object |
default | Error (RFC 9457 problem details) | Problem |
snapshots¶
PUT /api/v1/restore¶
Replace the tenant's store with an uploaded snapshot archive after verifying it.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Request body (required)
Content type application/x-tar: string (binary)
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Restored |
default | Error (RFC 9457 problem details) | Problem |
GET /api/v1/snapshots¶
List the tenant's snapshots.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Snapshots |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/snapshots¶
Snapshot the tenant's store on the server (the tenant pauses while it is copied).
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
201 | Success | Snapshot |
default | Error (RFC 9457 problem details) | Problem |
DELETE /api/v1/snapshots/{id}¶
Delete a snapshot.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
id | path | string | required | Snapshot id. |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Deleted |
default | Error (RFC 9457 problem details) | Problem |
GET /api/v1/snapshots/{id}/archive¶
Download a snapshot as a tar stream (the off-box backup format).
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
id | path | string | required | Snapshot id. |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Uncompressed tar of the store directory | string |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/snapshots/{id}/restore¶
Replace the tenant's store with a snapshot; the replaced store is kept as a snapshot.
| Parameter | In | Type | Description | |
|---|---|---|---|---|
X-Tenant-ID | header | string | Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else "default". | |
id | path | string | required | Snapshot id. |
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | Restored |
default | Error (RFC 9457 problem details) | Problem |
operations¶
GET /healthz¶
Liveness: the process is serving.
| Status | Description | Body |
|---|---|---|
200 | Success | Health |
default | Error (RFC 9457 problem details) | Problem |
GET /metrics¶
Prometheus metrics. Needs the admin scope unless --metrics-public is set.
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Prometheus text exposition format 0.0.4 | string |
default | Error (RFC 9457 problem details) | Problem |
GET /openapi.json¶
This document.
| Status | Description | Body |
|---|---|---|
200 | OpenAPI 3.1 document | object |
default | Error (RFC 9457 problem details) | Problem |
GET /readyz¶
Readiness: 200 while accepting work, 503 while starting or draining.
| Status | Description | Body |
|---|---|---|
200 | Success | Health |
default | Error (RFC 9457 problem details) | Problem |
Schemas¶
Added¶
| Field | Type | Description | |
|---|---|---|---|
added | integer (uint) | required | Incoming documents stored (a repeated id counts each occurrence). |
CompactionRun¶
| Field | Type | Description | |
|---|---|---|---|
status | CompactionView | required |
CompactionStatusBody¶
| Field | Type | Description | |
|---|---|---|---|
scheduled_interval_seconds | integer (uint64) | required | 0 when scheduled compaction is off. |
status | CompactionView | required |
CompactionView¶
| Field | Type | Description | |
|---|---|---|---|
failures | integer (uint64) | required | |
last_duration_ms | integer or null (uint64) | ||
last_error | string or null | ||
last_started_at | string or null | ||
last_trigger | string or null | ||
running | boolean | required | |
runs | integer (uint64) | required |
Deleted¶
| Field | Type | Description | |
|---|---|---|---|
deleted | boolean | required |
DocIn¶
One document. vector has exactly --input-dim finite numbers (omit it only when the server embeds text on-device).
| Field | Type | Description | |
|---|---|---|---|
id | string | required | |
metadata | object | ||
text | string or null | ||
vector | array or null |
DocumentPage¶
| Field | Type | Description | |
|---|---|---|---|
count | integer (uint) | required | Total documents in the tenant. |
documents | array of ListedDocument | required | |
next_cursor | string or null | Pass as after for the next page; null on the last page. |
Health¶
| Field | Type | Description | |
|---|---|---|---|
status | string | required |
KeysReloaded¶
| Field | Type | Description | |
|---|---|---|---|
keys | integer (uint) | required |
LegacyError¶
| Field | Type | Description | |
|---|---|---|---|
code | string | required | |
message | string | required |
LineError¶
| Field | Type | Description | |
|---|---|---|---|
line | integer (uint64) | required | 1-based line number in the stream. |
message | string | required |
ListedDocument¶
| Field | Type | Description | |
|---|---|---|---|
id | string | required | |
metadata | object | required |
Maintained¶
| Field | Type | Description | |
|---|---|---|---|
documentIndexTrained | boolean | required | |
vectorIndex | VectorIndexBody | required |
Match¶
| Field | Type | Description | |
|---|---|---|---|
id | string | required | |
metadata | object | required | |
score | number (double) | required | Exact cosine similarity for vector queries; fused rank score for text queries. |
text | string | required | Stored text, empty when the document was stored without text. |
Matches¶
| Field | Type | Description | |
|---|---|---|---|
matches | array of Match | required |
Problem¶
RFC 9457 problem details, plus the deprecated error object kept for v1 SDK clients.
| Field | Type | Description | |
|---|---|---|---|
code | string | required | |
detail | string | required | |
error | LegacyError | required | |
instance | string or null | ||
request_id | string or null | ||
status | integer (uint16) | required | |
title | string | required | |
type | string | required |
QueryIn¶
| Field | Type | Description | |
|---|---|---|---|
ef | integer or null (uint32) | Beam width of a graph-index query, 1..=4096 (recall knob). Default: --query-ef. | |
filter | object | Keep documents whose metadata contains every key with an equal JSON value. | |
index | string or null | Route of an unfiltered vector query: auto (the graph index when built, else the exact scan), exact or graph (409 index_unavailable until maintenance built one). Default: the server's --query-index. | |
query | string or null | Text query; requires the on-device model stages (local-models). | |
query_vector | array or null | Query embedding: exactly --input-dim finite numbers. | |
today | string or null | Date relative times in query resolve against (query rewriting). | |
top_k | integer or null (int64) | 1..=--max-top-k, default 3. |
Restored¶
| Field | Type | Description | |
|---|---|---|---|
previous_snapshot | string | required | The replaced store, kept as a snapshot with this id. |
restored | boolean | required |
SearchHit¶
One text search hit. text and metadata are present only when named in include.
| Field | Type | Description | |
|---|---|---|---|
id | string | required | |
metadata | object | ||
score | number (double) | required | BM25 score; the fused rank score when the server runs on-device model stages. |
text | string or null |
SearchHits¶
| Field | Type | Description | |
|---|---|---|---|
hits | array of SearchHit | required |
SearchIn¶
A lexical text query over the tenant's documents (memory facts included).
| Field | Type | Description | |
|---|---|---|---|
include | array of string | Extra fields per hit: any of "text" and "metadata". Default: ids and scores only. | |
query | string | required | 1..=8192 bytes with at least one word. |
top_k | integer or null (int64) | 1..=--max-top-k, default 10. |
Snapshot¶
| Field | Type | Description | |
|---|---|---|---|
bytes | integer (uint64) | required | |
created_at | string | required | |
id | string | required |
Snapshots¶
| Field | Type | Description | |
|---|---|---|---|
snapshots | array of Snapshot | required |
Stats¶
| Field | Type | Description | |
|---|---|---|---|
capacityBytes | number (double) | required | |
documentIndexTrained | boolean | required | |
documents | integer (uint) | required | |
tenant | string | required | |
usedBytes | number (double) | required | |
vectorIndex | VectorIndexBody | required | |
vectors | integer (uint) | required |
StreamResult¶
| Field | Type | Description | |
|---|---|---|---|
added | integer (uint64) | required | |
errors | array of LineError | required | The first rejected lines (at most 100). |
errors_truncated | boolean | required | |
rejected | integer (uint64) | required |
Tenants¶
| Field | Type | Description | |
|---|---|---|---|
open | integer (uint) | required | Stores currently open. |
tenants | array of string | required | Tenants with a store on disk. |
TlsReloaded¶
| Field | Type | Description | |
|---|---|---|---|
reloaded | boolean | required |
VectorIndexBody¶
The vector snapshot that answers unfiltered vector queries (see --query-index).
| Field | Type | Description | |
|---|---|---|---|
current | boolean | required | Whether the snapshot is the live store. A stale snapshot still answers correctly: deleted and replaced documents are dropped and new ones scored exactly. |
graph | boolean | required | Whether a graph index is built over the snapshot (auto queries use it). |
rebuildRecommended | boolean | required | Whether the next index maintenance or compaction will capture a fresh snapshot. |
rows | integer (uint) | required | Embedded chunks the snapshot covers; 0 until maintenance builds one. |
staleMutations | integer (uint64) | required | Inserts, replaces and deletes since the snapshot was captured. |