warm-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.5 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. | |
import_identity | query | string | Required matching lowercase SHA-256 owner digest when deleting an imported document. |
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
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | ForgetReport |
default | Error (RFC 9457 problem details) | Problem |
POST /api/v1/memory/capabilities¶
Discover and negotiate the temporal Memory contract; document pagination is a separate 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: CapabilitiesRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | CapabilitiesReply |
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
Content type application/json: object
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | ConsolidationReport |
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: ExplainRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | ExplainReply |
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: ForgetRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | ForgetReport |
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: IdRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | GetReply |
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: IdRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | HistoryReply |
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: RecallRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | RecallReply |
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: RememberRequest
Authentication: bearerAuth
| Status | Description | Body |
|---|---|---|
200 | Success | RememberReply |
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). |
CapabilitiesReply¶
| Field | Type | Description | |
|---|---|---|---|
capabilities | MemoryCapabilities | required |
CapabilitiesRequest¶
| Field | Type | Description | |
|---|---|---|---|
contractVersion | integer or null (uint32) |
ChainLink¶
| Field | Type | Description | |
|---|---|---|---|
effectiveFrom | integer (int64) | required | When the link takes effect on the valid-time axis. |
id | string | required | |
ingestTime | integer (int64) | required | |
relation | ChainRelation | required |
ChainRelation¶
Type: string or string
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 |
ConsolidationReport¶
What a consolidation run did or would do.
| Field | Type | Description | |
|---|---|---|---|
created | array of Remembered | required | Facts written; each supersedes its sources. |
dryRun | boolean | required | |
forgotten | array of string | required | Sources removed. Empty unless destructive consolidation was explicitly allowed. |
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 | |
import_adopt_legacy | boolean | Explicitly adopt a matching legacy source record without an owner stamp. | |
import_identity | string or null | Import-owner digest; must match metadata.warm_import_identity. | |
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. |
ExplainReply¶
| Field | Type | Description | |
|---|---|---|---|
explanation | Explanation | required |
ExplainRequest¶
| Field | Type | Description | |
|---|---|---|---|
asOf | integer or null (int64) | Evaluate validity and supersession at this time. Absent: the clock's now. | |
candidateLimit | integer or null (uint32) | Eligible candidates ranked before optional recency adjustment; defaults to document search's. | |
embedding | array or null | ||
entities | array or null | Only facts mentioning at least one of these entities. | |
explain | boolean | Attach an [Explanation] to every result. Costs nothing when false. | |
filter | object | Exact top-level metadata matches, as in document search. | |
fusion | string or null | "blend" (default) or "rrf", as in document search. | |
history | HistoryMode or null | Absent: the configured default. | |
id | string | required | |
k | integer or null (uint32) | Results to return; the configured default (10) when absent. At most 1000. | |
knownAt | integer or null (int64) | Evaluate what the store knew at this ingest time: later facts and later supersessions are ignored. Absent: everything stored. | |
lexicalWeight | number or null (double) | ||
minSemanticScore | number or null (double) | ||
query | string | required | |
semanticWeight | number or null (double) | ||
subject | string or null | Only facts about this subject. |
Explanation¶
Why a fact matched and how it was adjusted.
| Field | Type | Description | |
|---|---|---|---|
asOf | integer (int64) | required | |
chain | array of ChainLink | required | |
finalScore | number or null (double) | ||
fusion | string | required | |
historicalFactor | number (double) | required | The multiplier for a non-current fact (historicalWeight); 1 for a current one. |
knownAt | integer or null (int64) | ||
lexicalScore | number or null (double) | ||
lexicalWeight | number (double) | required | |
matchedTerms | array of string | required | Query words that match the fact's text (after stemming). |
rank | integer or null (uint) | 1-based position among the ranked candidates, after the recency policy. | |
recencyFactor | number (double) | required | The recency policy's multiplier; 1 when none is configured. |
retrievalScore | number or null (double) | The fused document search score before the recency policy. | |
retrieved | boolean | required | False when the fact was not among the ranked candidates for the query (explain still reports its terms, validity and chain). |
semanticScore | number or null (double) | ||
semanticWeight | number (double) | required | |
status | FactStatus | required | |
validFrom | integer or null (int64) | ||
validTo | integer or null (int64) | ||
withinValidity | boolean | required |
FactOrNull¶
Type: FactRecord or null
FactRecord¶
A stored fact with its history links, as get and history return it.
| Field | Type | Description | |
|---|---|---|---|
effectiveFrom | integer (int64) | required | When the fact takes effect on the valid-time axis. |
entities | array of string | required | |
eventTime | integer or null (int64) | ||
id | string | required | |
ingestTime | integer or null (int64) | ||
metadata | object | required | |
status | FactStatus | required | |
subject | string or null | ||
supersededBy | array of string | required | |
supersedes | array of string | required | |
text | string or null | ||
validFrom | integer or null (int64) | ||
validTo | integer or null (int64) |
FactStatus¶
A fact's standing at the time recall evaluates it.
Type: one of current or string or string or string
ForgetReport¶
| Field | Type | Description | |
|---|---|---|---|
dryRun | boolean | required | |
forgotten | array of string | required | Ids removed (or, for a dry run, that would be removed), sorted. |
purged | boolean | required |
ForgetRequest¶
| Field | Type | Description | |
|---|---|---|---|
dryRun | boolean | Report what would be removed without removing it. | |
includeChain | boolean | Also remove every fact linked to a matched one by supersession, in both directions, so no version of the chain survives. Default: only the matched facts; a successor's removal makes its predecessor current again. | |
purge | boolean | Compact the store afterwards. Deleted text stays in the append-only journal until a compaction rewrites it; this makes the removal physical. | |
scope | ForgetScope | required |
ForgetScope¶
What forget removes.
Type: object or object or object or object or object or object
GetReply¶
| Field | Type | Description | |
|---|---|---|---|
fact | FactOrNull | required |
Health¶
| Field | Type | Description | |
|---|---|---|---|
status | string | required |
HistoryMode¶
Which facts recall returns.
Type: string or string or string
HistoryReply¶
| Field | Type | Description | |
|---|---|---|---|
history | array of FactRecord | required |
IdRequest¶
get and history retain their legacy acceptance of extra request fields.
| Field | Type | Description | |
|---|---|---|---|
id | 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 |
MemoryCapabilities¶
| Field | Type | Description | |
|---|---|---|---|
committedErrorCode | string | required | |
contractVersion | integer (uint32) | required | |
documentPagination | boolean | required | |
exactMetadataFilters | boolean | required | |
operations | array of string | required | |
profile | string | required | |
subjectEntityFilters | boolean | required | |
temporalQueries | boolean | 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 | |
|---|---|---|---|
document_ids | array or null | Intersect metadata filtering with 1..=1000 explicit document IDs; uses exact scoring. | |
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. |
RecallReply¶
| Field | Type | Description | |
|---|---|---|---|
results | array of Recalled | required |
RecallRequest¶
| Field | Type | Description | |
|---|---|---|---|
asOf | integer or null (int64) | Evaluate validity and supersession at this time. Absent: the clock's now. | |
candidateLimit | integer or null (uint32) | Eligible candidates ranked before optional recency adjustment; defaults to document search's. | |
embedding | array or null | ||
entities | array or null | Only facts mentioning at least one of these entities. | |
explain | boolean | Attach an [Explanation] to every result. Costs nothing when false. | |
filter | object | Exact top-level metadata matches, as in document search. | |
fusion | string or null | "blend" (default) or "rrf", as in document search. | |
history | HistoryMode or null | Absent: the configured default. | |
k | integer or null (uint32) | Results to return; the configured default (10) when absent. At most 1000. | |
knownAt | integer or null (int64) | Evaluate what the store knew at this ingest time: later facts and later supersessions are ignored. Absent: everything stored. | |
lexicalWeight | number or null (double) | ||
minSemanticScore | number or null (double) | ||
query | string | required | |
semanticWeight | number or null (double) | ||
subject | string or null | Only facts about this subject. |
Recalled¶
One fact returned by recall.
| Field | Type | Description | |
|---|---|---|---|
entities | array of string | required | |
eventTime | integer or null (int64) | ||
explanation | Explanation or null | ||
id | string | required | |
ingestTime | integer or null (int64) | ||
metadata | object | required | The caller's metadata, without the reserved _mem key. |
score | number (double) | required | The document search score after the recency policy. |
sourceUri | string or null | ||
status | FactStatus | required | |
subject | string or null | ||
supersededBy | array of string | required | |
supersedes | array of string | required | |
text | string or null | ||
validFrom | integer or null (int64) | ||
validTo | integer or null (int64) |
RememberBatch¶
| Field | Type | Description | |
|---|---|---|---|
facts | array of RememberInput | required |
RememberInput¶
One fact to remember.
| Field | Type | Description | |
|---|---|---|---|
embedding | array or null | A dense embedding of the text, when the store has an embedding space. | |
entities | array or null | Entities the fact mentions; matched exactly by RecallOptions::entities. | |
eventTime | integer or null (int64) | When the thing the fact describes happened (for example a conversation's date). It is not the ingest time, which the store records itself. | |
id | string or null | Caller-chosen id. Absent: a deterministic id derived from the content, so retrying the same call stores the same fact once. Ids may not start with hms:. | |
metadata | object | Caller metadata (a JSON object); exact top-level matches work as recall filters. The key _mem is reserved. | |
sourceUri | string or null | ||
subject | string or null | What the fact is about; the key supersession policies match on. | |
supersedes | array or null | Ids of facts this one replaces. They are kept and stay queryable as history. | |
text | string | required | |
validFrom | integer or null (int64) | Start of the interval in which the fact holds. Absent: unbounded. | |
validTo | integer or null (int64) | End (exclusive) of the interval in which the fact holds. Absent: unbounded. |
RememberReply¶
| Field | Type | Description | |
|---|---|---|---|
remembered | array of Remembered | required |
RememberRequest¶
Type: RememberInput or RememberBatch
Remembered¶
What remember did with one fact.
| Field | Type | Description | |
|---|---|---|---|
created | boolean | required | False when the identical fact was already stored under this id (an idempotent retry). |
id | string | required | |
ingestTime | integer (int64) | required | |
supersededBy | array of string | required | Facts that already supersede this one (a late-arriving older fact). |
supersedes | array of string | required | Facts this one supersedes, explicit and policy-resolved. |
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. |