{
"components": {
"schemas": {
"Added": {
"properties": {
"added": {
"description": "Incoming documents stored (a repeated id counts each occurrence).",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"added"
],
"type": "object"
},
"CapabilitiesReply": {
"properties": {
"capabilities": {
"$ref": "#/components/schemas/MemoryCapabilities"
}
},
"required": [
"capabilities"
],
"type": "object"
},
"CapabilitiesRequest": {
"additionalProperties": false,
"properties": {
"contractVersion": {
"default": null,
"format": "uint32",
"maximum": 1,
"minimum": 1,
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"ChainLink": {
"properties": {
"effectiveFrom": {
"description": "When the link takes effect on the valid-time axis.",
"format": "int64",
"type": "integer"
},
"id": {
"type": "string"
},
"ingestTime": {
"format": "int64",
"type": "integer"
},
"relation": {
"$ref": "#/components/schemas/ChainRelation"
}
},
"required": [
"id",
"relation",
"effectiveFrom",
"ingestTime"
],
"type": "object"
},
"ChainRelation": {
"oneOf": [
{
"const": "predecessor",
"description": "This fact (transitively) supersedes the linked one.",
"type": "string"
},
{
"const": "successor",
"description": "The linked fact (transitively) supersedes this one.",
"type": "string"
}
]
},
"CompactionRun": {
"properties": {
"status": {
"$ref": "#/components/schemas/CompactionView"
}
},
"required": [
"status"
],
"type": "object"
},
"CompactionStatusBody": {
"properties": {
"scheduled_interval_seconds": {
"description": "0 when scheduled compaction is off.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"status": {
"$ref": "#/components/schemas/CompactionView"
}
},
"required": [
"scheduled_interval_seconds",
"status"
],
"type": "object"
},
"CompactionView": {
"properties": {
"failures": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"last_duration_ms": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"last_error": {
"type": [
"string",
"null"
]
},
"last_started_at": {
"type": [
"string",
"null"
]
},
"last_trigger": {
"type": [
"string",
"null"
]
},
"running": {
"type": "boolean"
},
"runs": {
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"running",
"runs",
"failures"
],
"type": "object"
},
"ConsolidationReport": {
"description": "What a consolidation run did or would do.",
"properties": {
"created": {
"description": "Facts written; each supersedes its sources.",
"items": {
"$ref": "#/components/schemas/Remembered"
},
"type": "array"
},
"dryRun": {
"type": "boolean"
},
"forgotten": {
"description": "Sources removed. Empty unless destructive consolidation was explicitly allowed.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"created",
"forgotten",
"dryRun"
],
"type": "object"
},
"Deleted": {
"properties": {
"deleted": {
"type": "boolean"
}
},
"required": [
"deleted"
],
"type": "object"
},
"DocIn": {
"description": "One document. `vector` has exactly `--input-dim` finite numbers (omit it only when the server\nembeds text on-device).",
"properties": {
"id": {
"type": "string"
},
"import_adopt_legacy": {
"default": false,
"description": "Explicitly adopt a matching legacy source record without an owner stamp.",
"type": "boolean"
},
"import_identity": {
"default": null,
"description": "Import-owner digest; must match metadata.warm_import_identity.",
"type": [
"string",
"null"
]
},
"metadata": {
"default": null
},
"text": {
"default": null,
"type": [
"string",
"null"
]
},
"vector": {
"default": null,
"items": {
"format": "double",
"type": "number"
},
"type": [
"array",
"null"
]
}
},
"required": [
"id"
],
"type": "object"
},
"DocumentPage": {
"properties": {
"count": {
"description": "Total documents in the tenant.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"documents": {
"items": {
"$ref": "#/components/schemas/ListedDocument"
},
"type": "array"
},
"next_cursor": {
"description": "Pass as `after` for the next page; null on the last page.",
"type": [
"string",
"null"
]
}
},
"required": [
"documents",
"count"
],
"type": "object"
},
"ExplainReply": {
"properties": {
"explanation": {
"$ref": "#/components/schemas/Explanation"
}
},
"required": [
"explanation"
],
"type": "object"
},
"ExplainRequest": {
"additionalProperties": false,
"properties": {
"asOf": {
"default": null,
"description": "Evaluate validity and supersession at this time. Absent: the clock's now.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"candidateLimit": {
"default": null,
"description": "Eligible candidates ranked before optional recency adjustment; defaults to document search's.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"embedding": {
"default": null,
"items": {
"format": "double",
"type": "number"
},
"type": [
"array",
"null"
]
},
"entities": {
"default": null,
"description": "Only facts mentioning at least one of these entities.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"explain": {
"default": false,
"description": "Attach an [`Explanation`] to every result. Costs nothing when false.",
"type": "boolean"
},
"filter": {
"default": null,
"description": "Exact top-level metadata matches, as in document search."
},
"fusion": {
"default": null,
"description": "`\"blend\"` (default) or `\"rrf\"`, as in document search.",
"type": [
"string",
"null"
]
},
"history": {
"anyOf": [
{
"$ref": "#/components/schemas/HistoryMode"
},
{
"type": "null"
}
],
"default": null,
"description": "Absent: the configured default."
},
"id": {
"type": "string"
},
"k": {
"default": null,
"description": "Results to return; the configured default (10) when absent. At most 1000.",
"format": "uint32",
"maximum": 1000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"knownAt": {
"default": null,
"description": "Evaluate what the store knew at this ingest time: later facts and later supersessions\nare ignored. Absent: everything stored.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"lexicalWeight": {
"default": null,
"format": "double",
"type": [
"number",
"null"
]
},
"minSemanticScore": {
"default": null,
"format": "double",
"type": [
"number",
"null"
]
},
"query": {
"type": "string"
},
"semanticWeight": {
"default": null,
"format": "double",
"type": [
"number",
"null"
]
},
"subject": {
"default": null,
"description": "Only facts about this subject.",
"type": [
"string",
"null"
]
}
},
"required": [
"query",
"id"
],
"type": "object"
},
"Explanation": {
"description": "Why a fact matched and how it was adjusted.",
"properties": {
"asOf": {
"format": "int64",
"type": "integer"
},
"chain": {
"items": {
"$ref": "#/components/schemas/ChainLink"
},
"type": "array"
},
"finalScore": {
"format": "double",
"type": [
"number",
"null"
]
},
"fusion": {
"type": "string"
},
"historicalFactor": {
"description": "The multiplier for a non-current fact (`historicalWeight`); 1 for a current one.",
"format": "double",
"type": "number"
},
"knownAt": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"lexicalScore": {
"format": "double",
"type": [
"number",
"null"
]
},
"lexicalWeight": {
"format": "double",
"type": "number"
},
"matchedTerms": {
"description": "Query words that match the fact's text (after stemming).",
"items": {
"type": "string"
},
"type": "array"
},
"rank": {
"description": "1-based position among the ranked candidates, after the recency policy.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"recencyFactor": {
"description": "The recency policy's multiplier; 1 when none is configured.",
"format": "double",
"type": "number"
},
"retrievalScore": {
"description": "The fused document search score before the recency policy.",
"format": "double",
"type": [
"number",
"null"
]
},
"retrieved": {
"description": "False when the fact was not among the ranked candidates for the query (explain\nstill reports its terms, validity and chain).",
"type": "boolean"
},
"semanticScore": {
"format": "double",
"type": [
"number",
"null"
]
},
"semanticWeight": {
"format": "double",
"type": "number"
},
"status": {
"$ref": "#/components/schemas/FactStatus"
},
"validFrom": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"validTo": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"withinValidity": {
"type": "boolean"
}
},
"required": [
"retrieved",
"lexicalWeight",
"semanticWeight",
"fusion",
"matchedTerms",
"recencyFactor",
"historicalFactor",
"status",
"asOf",
"withinValidity",
"chain"
],
"type": "object"
},
"FactOrNull": {
"anyOf": [
{
"$ref": "#/components/schemas/FactRecord"
},
{
"type": "null"
}
]
},
"FactRecord": {
"description": "A stored fact with its history links, as `get` and `history` return it.",
"properties": {
"effectiveFrom": {
"description": "When the fact takes effect on the valid-time axis.",
"format": "int64",
"type": "integer"
},
"entities": {
"items": {
"type": "string"
},
"type": "array"
},
"eventTime": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"id": {
"type": "string"
},
"ingestTime": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"metadata": true,
"status": {
"$ref": "#/components/schemas/FactStatus"
},
"subject": {
"type": [
"string",
"null"
]
},
"supersededBy": {
"items": {
"type": "string"
},
"type": "array"
},
"supersedes": {
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"type": [
"string",
"null"
]
},
"validFrom": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"validTo": {
"format": "int64",
"type": [
"integer",
"null"
]
}
},
"required": [
"id",
"status",
"effectiveFrom",
"entities",
"supersedes",
"supersededBy",
"metadata"
],
"type": "object"
},
"FactStatus": {
"description": "A fact's standing at the time recall evaluates it.",
"oneOf": [
{
"enum": [
"current"
],
"type": "string"
},
{
"const": "superseded",
"description": "A newer fact supersedes it; it stays stored as history.",
"type": "string"
},
{
"const": "expired",
"description": "Its validity interval ended.",
"type": "string"
},
{
"const": "not-yet-valid",
"description": "Its validity interval has not started.",
"type": "string"
}
]
},
"ForgetReport": {
"properties": {
"dryRun": {
"type": "boolean"
},
"forgotten": {
"description": "Ids removed (or, for a dry run, that would be removed), sorted.",
"items": {
"type": "string"
},
"type": "array"
},
"purged": {
"type": "boolean"
}
},
"required": [
"forgotten",
"dryRun",
"purged"
],
"type": "object"
},
"ForgetRequest": {
"additionalProperties": false,
"properties": {
"dryRun": {
"default": false,
"description": "Report what would be removed without removing it.",
"type": "boolean"
},
"includeChain": {
"default": false,
"description": "Also remove every fact linked to a matched one by supersession, in both directions,\nso no version of the chain survives. Default: only the matched facts; a successor's\nremoval makes its predecessor current again.",
"type": "boolean"
},
"purge": {
"default": false,
"description": "Compact the store afterwards. Deleted text stays in the append-only journal until a\ncompaction rewrites it; this makes the removal physical.",
"type": "boolean"
},
"scope": {
"$ref": "#/components/schemas/ForgetScope"
}
},
"required": [
"scope"
],
"type": "object"
},
"ForgetScope": {
"description": "What `forget` removes.",
"oneOf": [
{
"description": "These fact ids.",
"properties": {
"ids": {
"items": {
"type": "string"
},
"type": "array"
},
"kind": {
"const": "ids",
"type": "string"
}
},
"required": [
"kind",
"ids"
],
"type": "object"
},
{
"description": "Every fact about a subject.",
"properties": {
"kind": {
"const": "subject",
"type": "string"
},
"subject": {
"type": "string"
}
},
"required": [
"kind",
"subject"
],
"type": "object"
},
{
"description": "Every fact mentioning an entity.",
"properties": {
"entity": {
"type": "string"
},
"kind": {
"const": "entity",
"type": "string"
}
},
"required": [
"kind",
"entity"
],
"type": "object"
},
{
"description": "Facts ingested before this time.",
"properties": {
"kind": {
"const": "ingestedBefore",
"type": "string"
},
"time": {
"format": "int64",
"type": "integer"
}
},
"required": [
"kind",
"time"
],
"type": "object"
},
{
"description": "Facts whose event time (else valid-from, else ingest time) is before this time.",
"properties": {
"kind": {
"const": "eventBefore",
"type": "string"
},
"time": {
"format": "int64",
"type": "integer"
}
},
"required": [
"kind",
"time"
],
"type": "object"
},
{
"description": "Facts whose caller metadata contains all these top-level values.",
"properties": {
"filter": true,
"kind": {
"const": "matching",
"type": "string"
}
},
"required": [
"kind",
"filter"
],
"type": "object"
}
]
},
"GetReply": {
"properties": {
"fact": {
"$ref": "#/components/schemas/FactOrNull"
}
},
"required": [
"fact"
],
"type": "object"
},
"Health": {
"properties": {
"status": {
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
},
"HistoryMode": {
"description": "Which facts recall returns.",
"oneOf": [
{
"const": "current",
"description": "Only facts that are current at the evaluation time. The default.",
"type": "string"
},
{
"const": "all",
"description": "Every fact, with its status; ranking is unchanged.",
"type": "string"
},
{
"const": "historical",
"description": "Only facts that are not current: superseded, expired or not yet valid.",
"type": "string"
}
]
},
"HistoryReply": {
"properties": {
"history": {
"items": {
"$ref": "#/components/schemas/FactRecord"
},
"type": "array"
}
},
"required": [
"history"
],
"type": "object"
},
"IdRequest": {
"description": "`get` and `history` retain their legacy acceptance of extra request fields.",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"KeysReloaded": {
"properties": {
"keys": {
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"keys"
],
"type": "object"
},
"LegacyError": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"LineError": {
"properties": {
"line": {
"description": "1-based line number in the stream.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"line",
"message"
],
"type": "object"
},
"ListedDocument": {
"properties": {
"id": {
"type": "string"
},
"metadata": true
},
"required": [
"id",
"metadata"
],
"type": "object"
},
"Maintained": {
"properties": {
"documentIndexTrained": {
"type": "boolean"
},
"vectorIndex": {
"$ref": "#/components/schemas/VectorIndexBody"
}
},
"required": [
"documentIndexTrained",
"vectorIndex"
],
"type": "object"
},
"Match": {
"properties": {
"id": {
"type": "string"
},
"metadata": true,
"score": {
"description": "Exact cosine similarity for vector queries; fused rank score for text queries.",
"format": "double",
"type": "number"
},
"text": {
"description": "Stored text, empty when the document was stored without text.",
"type": "string"
}
},
"required": [
"id",
"text",
"metadata",
"score"
],
"type": "object"
},
"Matches": {
"properties": {
"matches": {
"items": {
"$ref": "#/components/schemas/Match"
},
"type": "array"
}
},
"required": [
"matches"
],
"type": "object"
},
"MemoryCapabilities": {
"properties": {
"committedErrorCode": {
"type": "string"
},
"contractVersion": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"documentPagination": {
"type": "boolean"
},
"exactMetadataFilters": {
"type": "boolean"
},
"operations": {
"items": {
"type": "string"
},
"type": "array"
},
"profile": {
"type": "string"
},
"subjectEntityFilters": {
"type": "boolean"
},
"temporalQueries": {
"type": "boolean"
}
},
"required": [
"contractVersion",
"profile",
"operations",
"temporalQueries",
"exactMetadataFilters",
"subjectEntityFilters",
"documentPagination",
"committedErrorCode"
],
"type": "object"
},
"Problem": {
"description": "RFC 9457 problem details, plus the deprecated `error` object kept for v1 SDK clients.",
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": "string"
},
"error": {
"$ref": "#/components/schemas/LegacyError"
},
"instance": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": [
"string",
"null"
]
},
"status": {
"format": "uint16",
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"title": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"title",
"status",
"detail",
"code",
"error"
],
"type": "object"
},
"QueryIn": {
"properties": {
"document_ids": {
"default": null,
"description": "Intersect metadata filtering with 1..=1000 explicit document IDs; uses exact scoring.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"ef": {
"default": null,
"description": "Beam width of a graph-index query, 1..=4096 (recall knob). Default: `--query-ef`.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"filter": {
"default": null,
"description": "Keep documents whose metadata contains every key with an equal JSON value."
},
"index": {
"default": null,
"description": "Route of an unfiltered vector query: `auto` (the graph index when built, else the\nexact scan), `exact` or `graph` (409 `index_unavailable` until maintenance built one).\nDefault: the server's `--query-index`.",
"type": [
"string",
"null"
]
},
"query": {
"default": null,
"description": "Text query; requires the on-device model stages (`local-models`).",
"type": [
"string",
"null"
]
},
"query_vector": {
"default": null,
"description": "Query embedding: exactly `--input-dim` finite numbers.",
"items": {
"format": "double",
"type": "number"
},
"type": [
"array",
"null"
]
},
"today": {
"default": null,
"description": "Date relative times in `query` resolve against (query rewriting).",
"type": [
"string",
"null"
]
},
"top_k": {
"default": null,
"description": "1..=`--max-top-k`, default 3.",
"format": "int64",
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"RecallReply": {
"properties": {
"results": {
"items": {
"$ref": "#/components/schemas/Recalled"
},
"type": "array"
}
},
"required": [
"results"
],
"type": "object"
},
"RecallRequest": {
"additionalProperties": false,
"properties": {
"asOf": {
"default": null,
"description": "Evaluate validity and supersession at this time. Absent: the clock's now.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"candidateLimit": {
"default": null,
"description": "Eligible candidates ranked before optional recency adjustment; defaults to document search's.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"embedding": {
"default": null,
"items": {
"format": "double",
"type": "number"
},
"type": [
"array",
"null"
]
},
"entities": {
"default": null,
"description": "Only facts mentioning at least one of these entities.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"explain": {
"default": false,
"description": "Attach an [`Explanation`] to every result. Costs nothing when false.",
"type": "boolean"
},
"filter": {
"default": null,
"description": "Exact top-level metadata matches, as in document search."
},
"fusion": {
"default": null,
"description": "`\"blend\"` (default) or `\"rrf\"`, as in document search.",
"type": [
"string",
"null"
]
},
"history": {
"anyOf": [
{
"$ref": "#/components/schemas/HistoryMode"
},
{
"type": "null"
}
],
"default": null,
"description": "Absent: the configured default."
},
"k": {
"default": null,
"description": "Results to return; the configured default (10) when absent. At most 1000.",
"format": "uint32",
"maximum": 1000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"knownAt": {
"default": null,
"description": "Evaluate what the store knew at this ingest time: later facts and later supersessions\nare ignored. Absent: everything stored.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"lexicalWeight": {
"default": null,
"format": "double",
"type": [
"number",
"null"
]
},
"minSemanticScore": {
"default": null,
"format": "double",
"type": [
"number",
"null"
]
},
"query": {
"type": "string"
},
"semanticWeight": {
"default": null,
"format": "double",
"type": [
"number",
"null"
]
},
"subject": {
"default": null,
"description": "Only facts about this subject.",
"type": [
"string",
"null"
]
}
},
"required": [
"query"
],
"type": "object"
},
"Recalled": {
"description": "One fact returned by recall.",
"properties": {
"entities": {
"items": {
"type": "string"
},
"type": "array"
},
"eventTime": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"explanation": {
"anyOf": [
{
"$ref": "#/components/schemas/Explanation"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"ingestTime": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"metadata": {
"description": "The caller's metadata, without the reserved `_mem` key."
},
"score": {
"description": "The document search score after the recency policy.",
"format": "double",
"type": "number"
},
"sourceUri": {
"type": [
"string",
"null"
]
},
"status": {
"$ref": "#/components/schemas/FactStatus"
},
"subject": {
"type": [
"string",
"null"
]
},
"supersededBy": {
"items": {
"type": "string"
},
"type": "array"
},
"supersedes": {
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"type": [
"string",
"null"
]
},
"validFrom": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"validTo": {
"format": "int64",
"type": [
"integer",
"null"
]
}
},
"required": [
"id",
"score",
"status",
"entities",
"supersedes",
"supersededBy",
"metadata"
],
"type": "object"
},
"RememberBatch": {
"additionalProperties": false,
"properties": {
"facts": {
"items": {
"$ref": "#/components/schemas/RememberInput"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"facts"
],
"type": "object"
},
"RememberInput": {
"additionalProperties": false,
"description": "One fact to remember.",
"properties": {
"embedding": {
"default": null,
"description": "A dense embedding of the text, when the store has an embedding space.",
"items": {
"format": "double",
"type": "number"
},
"type": [
"array",
"null"
]
},
"entities": {
"default": null,
"description": "Entities the fact mentions; matched exactly by `RecallOptions::entities`.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"eventTime": {
"default": null,
"description": "When the thing the fact describes happened (for example a conversation's date). It is\nnot the ingest time, which the store records itself.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"id": {
"default": null,
"description": "Caller-chosen id. Absent: a deterministic id derived from the content, so retrying the\nsame call stores the same fact once. Ids may not start with `hms:`.",
"type": [
"string",
"null"
]
},
"metadata": {
"default": null,
"description": "Caller metadata (a JSON object); exact top-level matches work as recall filters.\nThe key `_mem` is reserved."
},
"sourceUri": {
"default": null,
"type": [
"string",
"null"
]
},
"subject": {
"default": null,
"description": "What the fact is about; the key supersession policies match on.",
"type": [
"string",
"null"
]
},
"supersedes": {
"default": null,
"description": "Ids of facts this one replaces. They are kept and stay queryable as history.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"text": {
"default": "",
"minLength": 1,
"type": "string"
},
"validFrom": {
"default": null,
"description": "Start of the interval in which the fact holds. Absent: unbounded.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"validTo": {
"default": null,
"description": "End (exclusive) of the interval in which the fact holds. Absent: unbounded.",
"format": "int64",
"type": [
"integer",
"null"
]
}
},
"required": [
"text"
],
"type": "object"
},
"RememberReply": {
"properties": {
"remembered": {
"items": {
"$ref": "#/components/schemas/Remembered"
},
"type": "array"
}
},
"required": [
"remembered"
],
"type": "object"
},
"RememberRequest": {
"anyOf": [
{
"$ref": "#/components/schemas/RememberInput"
},
{
"$ref": "#/components/schemas/RememberBatch"
}
]
},
"Remembered": {
"description": "What `remember` did with one fact.",
"properties": {
"created": {
"description": "False when the identical fact was already stored under this id (an idempotent retry).",
"type": "boolean"
},
"id": {
"type": "string"
},
"ingestTime": {
"format": "int64",
"type": "integer"
},
"supersededBy": {
"description": "Facts that already supersede this one (a late-arriving older fact).",
"items": {
"type": "string"
},
"type": "array"
},
"supersedes": {
"description": "Facts this one supersedes, explicit and policy-resolved.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"id",
"created",
"supersedes",
"supersededBy",
"ingestTime"
],
"type": "object"
},
"Restored": {
"properties": {
"previous_snapshot": {
"description": "The replaced store, kept as a snapshot with this id.",
"type": "string"
},
"restored": {
"type": "boolean"
}
},
"required": [
"restored",
"previous_snapshot"
],
"type": "object"
},
"SearchHit": {
"description": "One text search hit. `text` and `metadata` are present only when named in `include`.",
"properties": {
"id": {
"type": "string"
},
"metadata": true,
"score": {
"description": "BM25 score; the fused rank score when the server runs on-device model stages.",
"format": "double",
"type": "number"
},
"text": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"score"
],
"type": "object"
},
"SearchHits": {
"properties": {
"hits": {
"items": {
"$ref": "#/components/schemas/SearchHit"
},
"type": "array"
}
},
"required": [
"hits"
],
"type": "object"
},
"SearchIn": {
"additionalProperties": false,
"description": "A lexical text query over the tenant's documents (memory facts included).",
"properties": {
"include": {
"default": [],
"description": "Extra fields per hit: any of `\"text\"` and `\"metadata\"`. Default: ids and scores only.",
"items": {
"type": "string"
},
"type": "array"
},
"query": {
"description": "1..=8192 bytes with at least one word.",
"type": "string"
},
"top_k": {
"default": null,
"description": "1..=`--max-top-k`, default 10.",
"format": "int64",
"type": [
"integer",
"null"
]
}
},
"required": [
"query"
],
"type": "object"
},
"Snapshot": {
"properties": {
"bytes": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"bytes",
"created_at"
],
"type": "object"
},
"Snapshots": {
"properties": {
"snapshots": {
"items": {
"$ref": "#/components/schemas/Snapshot"
},
"type": "array"
}
},
"required": [
"snapshots"
],
"type": "object"
},
"Stats": {
"properties": {
"capacityBytes": {
"format": "double",
"type": "number"
},
"documentIndexTrained": {
"type": "boolean"
},
"documents": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"tenant": {
"type": "string"
},
"usedBytes": {
"format": "double",
"type": "number"
},
"vectorIndex": {
"$ref": "#/components/schemas/VectorIndexBody"
},
"vectors": {
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"tenant",
"documents",
"vectors",
"documentIndexTrained",
"vectorIndex",
"usedBytes",
"capacityBytes"
],
"type": "object"
},
"StreamResult": {
"properties": {
"added": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"errors": {
"description": "The first rejected lines (at most 100).",
"items": {
"$ref": "#/components/schemas/LineError"
},
"type": "array"
},
"errors_truncated": {
"type": "boolean"
},
"rejected": {
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"added",
"rejected",
"errors",
"errors_truncated"
],
"type": "object"
},
"Tenants": {
"properties": {
"open": {
"description": "Stores currently open.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"tenants": {
"description": "Tenants with a store on disk.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"tenants",
"open"
],
"type": "object"
},
"TlsReloaded": {
"properties": {
"reloaded": {
"type": "boolean"
}
},
"required": [
"reloaded"
],
"type": "object"
},
"VectorIndexBody": {
"description": "The vector snapshot that answers unfiltered vector queries (see `--query-index`).",
"properties": {
"current": {
"description": "Whether the snapshot is the live store. A stale snapshot still answers correctly:\ndeleted and replaced documents are dropped and new ones scored exactly.",
"type": "boolean"
},
"graph": {
"description": "Whether a graph index is built over the snapshot (`auto` queries use it).",
"type": "boolean"
},
"rebuildRecommended": {
"description": "Whether the next index maintenance or compaction will capture a fresh snapshot.",
"type": "boolean"
},
"rows": {
"description": "Embedded chunks the snapshot covers; 0 until maintenance builds one.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"staleMutations": {
"description": "Inserts, replaces and deletes since the snapshot was captured.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"rows",
"graph",
"current",
"staleMutations",
"rebuildRecommended"
],
"type": "object"
}
},
"securitySchemes": {
"bearerAuth": {
"description": "API key. Scopes: read, write, admin (admin includes read and write). Keys are bound to tenants.",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"description": "One engine store per tenant. The /api/v1 contract is stable: see docs/server/versioning.md. Errors are RFC 9457 problem details.",
"license": {
"identifier": "Apache-2.0",
"name": "Apache-2.0"
},
"summary": "WARM HTTP service",
"title": "warm-server",
"version": "0.6.5"
},
"openapi": "3.1.0",
"paths": {
"/api/v1/admin/keys/reload": {
"post": {
"operationId": "reloadKeys",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KeysReloaded"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Re-read --keys-file. Needs an all-tenant admin key.",
"tags": [
"admin"
]
}
},
"/api/v1/admin/tenants": {
"get": {
"operationId": "listTenants",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tenants"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Tenants with a store on disk. Needs an all-tenant admin key.",
"tags": [
"admin"
]
}
},
"/api/v1/admin/tls/reload": {
"post": {
"operationId": "reloadTls",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TlsReloaded"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Re-read --tls-cert and --tls-key. Needs an all-tenant admin key.",
"tags": [
"admin"
]
}
},
"/api/v1/compaction": {
"get": {
"operationId": "compactionStatus",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompactionStatusBody"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Compaction status and schedule for the tenant.",
"tags": [
"index"
]
},
"post": {
"operationId": "runCompaction",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompactionRun"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Compact the tenant's store now.",
"tags": [
"index"
]
}
},
"/api/v1/documents": {
"get": {
"operationId": "listDocuments",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Page size, 1..=1000 (default 100).",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer"
}
},
{
"description": "The next_cursor of the previous page.",
"in": "query",
"name": "after",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentPage"
}
}
},
"description": "Success"
},
"304": {
"description": "ETag matched If-None-Match"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "List document ids and metadata, paginated by id cursor.",
"tags": [
"documents"
]
},
"post": {
"operationId": "addDocument",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocIn"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Added"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Store or replace one document.",
"tags": [
"documents"
]
}
},
"/api/v1/documents/batch": {
"post": {
"operationId": "addDocuments",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DocIn"
},
"type": "array"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Added"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Store or replace up to --max-batch documents in one atomic commit.",
"tags": [
"documents"
]
}
},
"/api/v1/documents/stream": {
"post": {
"operationId": "streamDocuments",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/x-ndjson": {
"schema": {
"format": "binary",
"type": "string"
}
}
},
"description": "One document object per line",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StreamResult"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Bulk ingest newline-delimited documents, committed in batches; not atomic across batches.",
"tags": [
"documents"
]
}
},
"/api/v1/documents/{id}": {
"delete": {
"operationId": "deleteDocument",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Document id, percent-encoded.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "true also rewrites the journal and scrubs what the deleted document left behind.",
"in": "query",
"name": "purge",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Required matching lowercase SHA-256 owner digest when deleting an imported document.",
"in": "query",
"name": "import_identity",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Deleted"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Delete a document by id (percent-encoded).",
"tags": [
"documents"
]
}
},
"/api/v1/index/maintain": {
"post": {
"operationId": "maintainIndex",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"maxProperties": 0,
"type": "object"
}
}
},
"required": false
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Maintained"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Train the tenant's document index over stored embeddings.",
"tags": [
"index"
]
}
},
"/api/v1/memory/applyForgetting": {
"post": {
"operationId": "memoryApplyForgetting",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"dryRun": {
"default": true,
"description": "Report what would be removed without removing it.",
"type": "boolean"
},
"includeChain": {
"default": false,
"description": "Also remove every fact linked to a matched one by supersession, in both directions,\nso no version of the chain survives. Default: only the matched facts; a successor's\nremoval makes its predecessor current again.",
"type": "boolean"
},
"purge": {
"default": false,
"description": "Compact the store afterwards. Deleted text stays in the append-only journal until a\ncompaction rewrites it; this makes the removal physical.",
"type": "boolean"
}
},
"type": "object"
}
}
},
"required": false
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForgetReport"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Apply the configured forgetting policy. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/capabilities": {
"post": {
"operationId": "memoryCapabilities",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapabilitiesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapabilitiesReply"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Discover and negotiate the temporal Memory contract; document pagination is a separate API.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/consolidate": {
"post": {
"operationId": "memoryConsolidate",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"allowDestructive": {
"default": false,
"description": "Honor a policy's request to remove consolidated sources. Without it sources remain as\nsuperseded history.",
"type": "boolean"
},
"dryRun": {
"default": true,
"type": "boolean"
}
},
"type": "object"
}
}
},
"required": false
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsolidationReport"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Run the configured consolidation policy. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/explain": {
"post": {
"operationId": "memoryExplain",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExplainRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExplainReply"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Recall with the evidence behind each result and its supersession chain. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/forget": {
"post": {
"operationId": "memoryForget",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForgetRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForgetReport"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Forget facts by id, source or scope. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/get": {
"post": {
"operationId": "memoryGet",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetReply"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Fetch one fact by id. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/history": {
"post": {
"operationId": "memoryHistory",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoryReply"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "A fact's version and supersession history. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/recall": {
"post": {
"operationId": "memoryRecall",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallReply"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Retrieve facts for a query, honoring validity time and supersession. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/memory/remember": {
"post": {
"operationId": "memoryRemember",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Replays the recorded response for a retried request (1..=128 visible ASCII characters).",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RememberRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RememberReply"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"write"
]
}
],
"summary": "Store one fact or an array of facts with validity time, source and supersession. See docs/memory-api.",
"tags": [
"memory"
]
}
},
"/api/v1/query": {
"post": {
"operationId": "query",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryIn"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Matches"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Nearest documents to a vector, best first, with exact cosine scores.",
"tags": [
"documents"
]
}
},
"/api/v1/restore": {
"put": {
"operationId": "restoreUpload",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/x-tar": {
"schema": {
"format": "binary",
"type": "string"
}
}
},
"description": "Tar produced by the archive endpoint",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Restored"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Replace the tenant's store with an uploaded snapshot archive after verifying it.",
"tags": [
"snapshots"
]
}
},
"/api/v1/search": {
"post": {
"operationId": "search",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchIn"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchHits"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Text search: document ids and scores, best first (BM25, or the on-device model stages when configured); stored text and metadata on request.",
"tags": [
"documents"
]
}
},
"/api/v1/snapshots": {
"get": {
"operationId": "listSnapshots",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Snapshots"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "List the tenant's snapshots.",
"tags": [
"snapshots"
]
},
"post": {
"operationId": "createSnapshot",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Snapshot"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Snapshot the tenant's store on the server (the tenant pauses while it is copied).",
"tags": [
"snapshots"
]
}
},
"/api/v1/snapshots/{id}": {
"delete": {
"operationId": "deleteSnapshot",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Snapshot id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Deleted"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Delete a snapshot.",
"tags": [
"snapshots"
]
}
},
"/api/v1/snapshots/{id}/archive": {
"get": {
"operationId": "downloadSnapshot",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Snapshot id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/x-tar": {
"schema": {
"type": "string"
}
}
},
"description": "Uncompressed tar of the store directory"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Download a snapshot as a tar stream (the off-box backup format).",
"tags": [
"snapshots"
]
}
},
"/api/v1/snapshots/{id}/restore": {
"post": {
"operationId": "restoreSnapshot",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Snapshot id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Restored"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Replace the tenant's store with a snapshot; the replaced store is kept as a snapshot.",
"tags": [
"snapshots"
]
}
},
"/api/v1/stats": {
"get": {
"operationId": "stats",
"parameters": [
{
"description": "Tenant whose store is used: 1..=64 of [A-Za-z0-9_-]. Defaults to the key's only tenant, else \"default\".",
"in": "header",
"name": "X-Tenant-ID",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"type": "string"
}
},
{
"description": "Return 304 when the ETag still matches.",
"in": "header",
"name": "If-None-Match",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Stats"
}
}
},
"description": "Success"
},
"304": {
"description": "ETag matched If-None-Match"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"read"
]
}
],
"summary": "Document and vector counts and storage use for the tenant.",
"tags": [
"documents"
]
}
},
"/healthz": {
"get": {
"operationId": "healthz",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [],
"summary": "Liveness: the process is serving.",
"tags": [
"operations"
]
}
},
"/metrics": {
"get": {
"operationId": "metrics",
"parameters": [],
"responses": {
"200": {
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"description": "Prometheus text exposition format 0.0.4"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [
{
"bearerAuth": [
"admin"
]
}
],
"summary": "Prometheus metrics. Needs the admin scope unless --metrics-public is set.",
"tags": [
"operations"
]
}
},
"/openapi.json": {
"get": {
"operationId": "openapi",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "OpenAPI 3.1 document"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [],
"summary": "This document.",
"tags": [
"operations"
]
}
},
"/readyz": {
"get": {
"operationId": "readyz",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error (RFC 9457 problem details)"
}
},
"security": [],
"summary": "Readiness: 200 while accepting work, 503 while starting or draining.",
"tags": [
"operations"
]
}
}
},
"servers": [
{
"url": "/"
}
],
"tags": [
{
"name": "documents"
},
{
"name": "memory"
},
{
"name": "index"
},
{
"name": "snapshots"
},
{
"name": "admin"
},
{
"name": "operations"
}
]
}