{
"openapi": "3.1.0",
"info": {
"title": "Areev API",
"description": "Areev — Reference implementation of the Open Memory Specification (.mg format). A compliance-native knowledge database for AI agents with hash-chained, cryptographically verifiable, immutable memory.",
"contact": {
"name": "Areev",
"url": "https://areev.ai"
},
"license": {
"name": "BUSL-1.1",
"url": "https://github.com/areev-project/areev/blob/main/LICENSE"
},
"version": "0.1.0"
},
"servers": [
{
"url": "/api",
"description": "Areev API base path"
}
],
"paths": {
"/config": {
"get": {
"tags": [
"health"
],
"summary": "GET /api/config — App deployment configuration.",
"description": "Public endpoint (no auth required). Returns deployment mode, auth strategy,\nand build-time capabilities so the Angular app can adapt its UI before\nthe user logs in.",
"operationId": "get_app_config",
"responses": {
"200": {
"description": "App deployment configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppConfigResponse"
}
}
}
}
}
}
},
"/crypto/workspace-dek": {
"post": {
"tags": [
"crypto"
],
"summary": "Create a workspace DEK (data encryption key) for envelope encryption of ML model artifacts.",
"description": "The DEK is generated by the KeyManager and wrapped by the master key.\nOnly metadata (version, timestamp, fingerprint) is returned — the raw DEK is never exposed\non the create path. Use the unwrap endpoint to retrieve the raw DEK for encryption/decryption.",
"operationId": "create_workspace_dek",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkspaceDekRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "DEK created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkspaceDekResponse"
}
}
}
},
"400": {
"description": "Invalid workspace_id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Crypto scope required (admin also accepted)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "DEK already exists for this workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "Workspace key was crypto-erased",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
}
]
}
},
"/crypto/workspace-dek/unwrap": {
"post": {
"tags": [
"crypto"
],
"summary": "Unwrap (retrieve) a workspace DEK for encryption/decryption of ML model artifacts.",
"description": "The raw DEK is returned base64-encoded. The response includes `Cache-Control: no-store`\nand `Pragma: no-cache` headers to prevent caching of key material.\n\n**SECURITY**: Audit trail write is fail-closed — if audit append fails, the DEK is NOT\nreturned and the handler responds with HTTP 500. This ensures every unwrap is audited.",
"operationId": "unwrap_workspace_dek",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnwrapWorkspaceDekRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "DEK unwrapped",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnwrapWorkspaceDekResponse"
}
}
}
},
"400": {
"description": "Invalid workspace_id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Crypto scope required (admin also accepted)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "No DEK for this workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"410": {
"description": "Workspace key was crypto-erased",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
}
]
}
},
"/health": {
"get": {
"tags": [
"health"
],
"operationId": "health",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthResponse"
}
}
}
}
}
}
},
"/memories": {
"get": {
"tags": [
"memories"
],
"operationId": "list_memories",
"parameters": [
{
"name": "offset",
"in": "query",
"description": "Number of items to skip (default 0).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum items to return (default: all). Max 200.",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "search",
"in": "query",
"description": "Filter by name (case-insensitive substring match).",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoriesListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"memories"
],
"operationId": "create_memory",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMemoryRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoryResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Memory with this name already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}": {
"get": {
"tags": [
"memories"
],
"operationId": "get_memory",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoryResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"memories"
],
"operationId": "delete_memory_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Memory deleted (no content)"
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/accumulate": {
"post": {
"tags": [
"grains"
],
"summary": "Accumulate delta updates into a grain's current tip.",
"operationId": "accumulate_grain",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccumulateAppRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Accumulated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccumulateAppResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Grain not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Supersession conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/add": {
"post": {
"tags": [
"grains"
],
"description": "Triple-store API: stores a Fact grain indexed by subject/relation/object. All three fields are indexed in the hexastore for graph traversal and triple-pattern queries. For typed grains (event, state, workflow, tool, etc.) without triple indexing, use POST /memories/{memory_id}/batch-add instead. Consent grains require both `subject_did` and `user_id` fields; omitting either returns 422. When `namespace` is unspecified, the server picks an existing namespace if any exist; the namespace cap does not apply.",
"operationId": "add_grain",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppAddGrainRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppAddGrainResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "SYS-E010 admission-shed — service overloaded; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/admin/reload-predicates": {
"post": {
"tags": [
"admin"
],
"summary": "POST /api/memories/{memory_id}/admin/reload-predicates — hot-reload the\npredicate cardinality registry from disk. Admin scope. Returns the diff\n(promoted/demoted/removed predicates) plus old + new version hashes.",
"description": "Audit-before-response (security S3): the `PredicateRegistryReloaded`\naudit event is appended before this handler returns 200. If the audit\nwrite fails, the new registry is still active (correctness wins) but\nthe handler returns 500 with the audit error so the operator knows\nthe audit record is missing.",
"operationId": "reload_predicates_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Reload succeeded; body contains diff + version hashes",
"content": {
"application/json": {
"schema": {}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Reload or audit failed (see error code)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/agents/identities": {
"get": {
"tags": [
"agent-identity"
],
"summary": "GET /api/memories/:id/agents/identities",
"operationId": "list_agent_identities",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of registered agent identities",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentIdentitiesListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"agent-identity"
],
"summary": "POST /api/memories/:id/agents/identities",
"operationId": "register_agent_identity",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterAgentIdentityRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Agent identity registered",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentIdentityResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/agents/identities/{agent_id}": {
"get": {
"tags": [
"agent-identity"
],
"summary": "GET /api/memories/:id/agents/identities/:agent_id",
"operationId": "get_agent_identity",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "agent_id",
"in": "path",
"description": "Agent ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agent identity details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentIdentityResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agent identity not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/agents/identities/{agent_id}/deactivate": {
"post": {
"tags": [
"agent-identity"
],
"summary": "POST /api/memories/:id/agents/identities/:agent_id/deactivate",
"operationId": "deactivate_agent_identity",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "agent_id",
"in": "path",
"description": "Agent ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agent deactivated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOkResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient permissions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agent identity not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/alerts": {
"get": {
"tags": [
"alerts"
],
"summary": "GET /api/memories/:id/alerts — aggregated \"needs your attention\" alerts.",
"description": "Combines 5 alert sources server-side: compliance failures, contradictions,\npolicy enforcement, retention lifecycle, and red/yellow metrics.",
"operationId": "alerts",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum alerts to return (1–100, default 20).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Aggregated alerts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertsResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/app/exec": {
"post": {
"tags": [
"grains"
],
"operationId": "app_exec",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/audit": {
"get": {
"tags": [
"compliance"
],
"operationId": "audit_log",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "offset",
"in": "query",
"description": "Number of entries to skip before returning results.",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "user_id",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "event_type",
"in": "query",
"description": "Filter by event type (e.g. \"grain_created\", \"crypto_erase\").",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "query",
"in": "query",
"description": "Search text in audit details.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "grain_hash",
"in": "query",
"description": "Filter audit entries for a specific grain hash.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "from",
"in": "query",
"description": "Start of time range (epoch milliseconds, inclusive).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
{
"name": "to",
"in": "query",
"description": "End of time range (epoch milliseconds, inclusive).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditAppResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/authz/check": {
"get": {
"tags": [
"authz"
],
"operationId": "authz_check",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "principal",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "permission",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "resource_type",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "resource_id",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthzCheckAppResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/authz/grant": {
"post": {
"tags": [
"authz"
],
"summary": "POST /memories/{memory_id}/authz/grant — Grant a Zanzibar authorization tuple (D04).",
"description": "Requires `admin` scope (S4). In distributed mode, pseudonymizes the subject and submits\na `GrantAuthz` command via Raft so all nodes receive the tuple. In standalone mode,\nwrites directly to the local authz partition.",
"operationId": "authz_grant",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthzGrantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthzGrantResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/authz/revoke": {
"post": {
"tags": [
"authz"
],
"summary": "POST /memories/{memory_id}/authz/revoke — Revoke a Zanzibar authorization tuple (D04).",
"description": "Requires `admin` scope (S4). In distributed mode, pseudonymizes the subject and submits\na `RevokeAuthz` command via Raft so all nodes remove the tuple. In standalone mode,\nremoves directly from the local authz partition.",
"operationId": "authz_revoke",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthzGrantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthzRevokeResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/batch-add": {
"post": {
"tags": [
"import"
],
"description": "Typed grain API: stores grains of any of the 11 OMS grain types. `fields.subject` is NOT indexed to the triple-store subject index — use POST /add for facts that need graph traversal. Returns HTTP 400 if all grains fail, HTTP 207 if partially added, HTTP 201 if all succeed.",
"operationId": "batch_add",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchAddRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "All grains added successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchAddResponse"
}
}
}
},
"207": {
"description": "Partial success — some grains added, some failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchAddResponse"
}
}
}
},
"400": {
"description": "All grains failed validation or invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/cal": {
"post": {
"tags": [
"grains"
],
"summary": "Execute a CAL query",
"description": "Execute a Context Assembly Language (CAL) query against the memory. Accepts CAL text (Content-Type: text/cal) or JSON-CAL (Content-Type: application/json). Supports RECALL, ASSEMBLE, STREAM ASSEMBLE, and FORMAT statements. STREAM ASSEMBLE returns Server-Sent Events (SSE).",
"operationId": "cal_query",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "CAL query string",
"content": {
"text/cal": {
"schema": {
"type": "string"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "CAL query result (JSON object with query, query_hash, result, warnings, metadata)"
},
"400": {
"description": "CAL parse or validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/chat": {
"post": {
"tags": [
"chat"
],
"summary": "POST /api/memories/{memory_id}/chat — conversational memory engine with A2UI.",
"description": "Streams SSE events: text deltas, A2UI JSONL surfaces, tool calls/results, done.\nHIPAA hard-block: returns 403 if HIPAA policy is active.",
"operationId": "chat_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "SSE event stream (text, a2ui, tool_call, tool_result, done, error)",
"content": {
"text/event-stream": {}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "HIPAA policy blocks chat",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/chat/stream": {
"post": {
"tags": [
"llm"
],
"summary": "POST /api/memories/:id/chat/stream — proxy streaming LLM chat completions.",
"description": "Streams the provider's SSE response directly to the browser.\nThe API key is read from server-side encrypted settings and never exposed to the client.",
"operationId": "chat_stream",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatStreamRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "SSE event stream",
"content": {
"text/event-stream": {}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/chat/threads": {
"get": {
"tags": [
"chat"
],
"summary": "GET /api/memories/{memory_id}/chat/threads — list chat threads.",
"operationId": "list_chat_threads",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max threads to return (1-100, default 20)",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"name": "cursor",
"in": "query",
"description": "Pagination cursor",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Thread list"
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"chat"
],
"summary": "POST /api/memories/{memory_id}/chat/threads — create a new chat thread.",
"operationId": "create_chat_thread",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateThreadRequest"
}
}
}
},
"responses": {
"201": {
"description": "Thread created"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/chat/threads/{thread_id}": {
"get": {
"tags": [
"chat"
],
"summary": "GET /api/memories/{memory_id}/chat/threads/{thread_id} — get a single thread.",
"operationId": "get_chat_thread",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "thread_id",
"in": "path",
"description": "Thread ID (UUID)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Thread details"
},
"400": {
"description": "Invalid thread ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"chat"
],
"summary": "DELETE /api/memories/{memory_id}/chat/threads/{thread_id} — delete a thread and its messages.",
"operationId": "delete_chat_thread",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "thread_id",
"in": "path",
"description": "Thread ID (UUID)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Thread deleted"
},
"400": {
"description": "Invalid thread ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"patch": {
"tags": [
"chat"
],
"summary": "PATCH /api/memories/{memory_id}/chat/threads/{thread_id} — rename a thread.",
"operationId": "rename_chat_thread",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "thread_id",
"in": "path",
"description": "Thread ID (UUID)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Thread renamed"
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/chat/threads/{thread_id}/messages": {
"get": {
"tags": [
"chat"
],
"summary": "GET /api/memories/{memory_id}/chat/threads/{thread_id}/messages — list thread messages.",
"operationId": "list_chat_thread_messages",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "thread_id",
"in": "path",
"description": "Thread ID (UUID)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max messages to return (1-100, default 50)",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"name": "cursor",
"in": "query",
"description": "Pagination cursor (seq number)",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "before",
"in": "query",
"description": "Load messages before this seq (or 'latest' for most recent). Mutually exclusive with cursor.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Message list"
},
"400": {
"description": "Invalid thread ID or cursor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/chat/tools/{tool}": {
"post": {
"tags": [
"chat"
],
"summary": "POST /api/memories/:id/chat/tools/:tool",
"description": "Deterministic chat-tool dispatch for a2ui button clicks. Body carries either `context` (flat string map from the a2ui Button action) or `params` (raw JSON). Authz mirrors the LLM tool-call path.",
"operationId": "chat_tool_dispatch",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tool",
"in": "path",
"description": "Chat tool name (e.g. run_saved_query)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatToolDispatchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Tool executed; response carries text + optional a2ui_messages.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatToolDispatchResponse"
}
}
}
},
"400": {
"description": "Bad request — invalid params or missing CAL source",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope for the tool",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found OR unknown tool name OR saved item not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Saved item name conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/breach": {
"post": {
"tags": [
"compliance"
],
"summary": "`POST /memories/{memory_id}/compliance/breach` — report a data breach for\nPDPC notification tracking (issue #572, PDPA M3b). Admin-scoped. Notifiable\nbreaches (≥500 affected OR significant harm) append a tamper-evident\n`PdpcBreachNotificationRequired` audit event and start the internal 48h /\nstatutory 72h deadline clock; non-notifiable reports record nothing.",
"operationId": "report_breach",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BreachReportRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Breach assessed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BreachReportResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/breach-deadlines": {
"get": {
"tags": [
"compliance"
],
"summary": "`GET /memories/{memory_id}/compliance/breach-deadlines` — list stored\nbreach-notification deadlines for the compliance dashboard (issue #572).",
"operationId": "breach_deadlines",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Open + resolved breach deadlines",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BreachDeadlineView"
}
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/breach/{breach_id}/resolve": {
"post": {
"tags": [
"compliance"
],
"summary": "`POST /memories/{memory_id}/compliance/breach/{breach_id}/resolve` — mark a\nbreach's PDPC notification as filed (issue #572). Admin-scoped. Resolved\nbreaches drop out of the overdue sweep.",
"operationId": "resolve_breach",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "breach_id",
"in": "path",
"description": "Breach ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Breach marked resolved"
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory or breach not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/export": {
"get": {
"tags": [
"compliance"
],
"summary": "GET /api/memories/:id/compliance/export",
"operationId": "compliance_export",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Full compliance report. Response shape varies by format query param (json|text|csv). JSON format returns a complex object with checks, summary, and metadata.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/impact": {
"get": {
"tags": [
"compliance"
],
"summary": "GET /api/memories/:id/compliance/impact",
"description": "Query params:\n - format: json (default), text, nist, colorado, iso42001\n - critical_threshold: number of failed checks to trigger Critical risk\n - disparity_threshold: disparity multiplier (e.g. 2.0)",
"operationId": "compliance_impact",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Compliance impact assessment: array of {framework, risk_level} objects per applicable regulation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ComplianceImpactResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/metrics": {
"get": {
"tags": [
"compliance"
],
"summary": "GET /api/memories/:id/compliance/metrics",
"description": "Returns compliance check summary. `failed` = total_checks - passed (includes Fail, Warn, and Skip statuses). This is consistent with POST /verify/run's counting method.",
"operationId": "compliance_metrics",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Compliance metrics summary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ComplianceMetricsResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/compliance/violations": {
"get": {
"tags": [
"compliance"
],
"summary": "GET /api/memories/:id/compliance/violations",
"operationId": "compliance_violations",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "regulation",
"in": "path",
"description": "Filter by regulation (e.g. \"GDPR\", \"HIPAA\", \"PII\").",
"required": true,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "sort",
"in": "path",
"description": "Sort order: \"severity\" (Critical first) or default (by check_id).",
"required": true,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "Compliance violations: violations array (check_id, group, description, detail, severity, regulation, article), total_checks, passed, failed, regulation_counts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ComplianceViolationsResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/consent/check": {
"get": {
"tags": [
"consent"
],
"summary": "GET /memories/{id}/consent/check?user_id=…&purpose=…&disclosure_version=…",
"description": "Per-`(user_id, purpose, disclosure_version)` consent lookup powering\nthe user-driven SSOT modal. `disclosure_version` is REQUIRED (compliance\nverdict §C5) — without it, legacy `disclosure_version: None` records\nwould silently satisfy SSOT-path checks.",
"operationId": "consent_check",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "query",
"description": "User principal to check",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "purpose",
"in": "query",
"description": "Consent purpose key",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "disclosure_version",
"in": "query",
"description": "Disclosure-copy version the modal showed (required)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consent state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentCheckResponse"
}
}
}
},
"400": {
"description": "Validation error (POL-E011/E012)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Cross-user check requires admin (POL-E010)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/consent/grant": {
"post": {
"tags": [
"consent"
],
"summary": "POST /memories/{id}/consent/grant — grant consent for a single user.",
"operationId": "consent_grant",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentGrantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Consent granted"
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/consent/grant-bulk": {
"post": {
"tags": [
"consent"
],
"summary": "POST /memories/{id}/consent/grant-bulk — grant consent for multiple users.",
"operationId": "consent_grant_bulk",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentBulkGrantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Bulk consent granted"
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/consent/revoke": {
"post": {
"tags": [
"consent"
],
"summary": "POST /memories/{id}/consent/revoke — revoke consent for a single user.",
"operationId": "consent_revoke",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentGrantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Consent revoked"
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/consent/status": {
"get": {
"tags": [
"consent"
],
"summary": "GET /memories/{id}/consent/status — check consent status for all users.",
"description": "SEC-PROBE-04: By default returns counts only. Pass `?include_ids=true` to\ninclude the list of non-consenting user IDs (generates an audit event).",
"operationId": "consent_status",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "include_ids",
"in": "query",
"description": "Include non-consenting user ID list (default: false)",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Consent status for all users",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentStatusResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/detect-pii": {
"post": {
"tags": [
"compliance"
],
"summary": "POST /api/memories/:id/detect-pii",
"description": "Detect PII/PHI in text with optional detailed match information.\nWhen `detailed` is true, returns positions, confidence, and source (DetectPiiDetailedResponse).\nWhen `detailed` is false or absent (default), returns category tags only: {detections: [\"EMAIL\", \"PHONE\", ...]}.",
"operationId": "detect_pii_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetectPiiDetailedRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Simple mode (detailed=false or absent): {detections: array[string]} — category tags only",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PiiResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/events": {
"get": {
"tags": [
"intelligence"
],
"summary": "GET /api/memories/{memory_id}/events — Poll for recent engine events",
"description": "Subscribes to the engine event broadcast and waits up to `timeout_ms`\n(default: 5000) for events. Returns collected events as a JSON array.\nThis is a long-polling endpoint — the client should call it in a loop.",
"operationId": "session_events_sse",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "timeout_ms",
"in": "query",
"description": "Max time to wait for events in milliseconds (default: 5000, max: 30000).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "max_events",
"in": "query",
"description": "Max events to return (default: 100, max: 1000).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "SSE event stream",
"content": {
"text/event-stream": {}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/export-file": {
"get": {
"tags": [
"import-export"
],
"operationId": "export_file",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "namespace",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "grain_type",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "OMS .mg wire stream download",
"content": {
"application/x-mg-stream": {}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/export/{user_id}": {
"get": {
"tags": [
"compliance"
],
"operationId": "export_user",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "path",
"description": "User ID to export",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportUserResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Can only export own data or requires admin scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/extract-document": {
"post": {
"tags": [
"import"
],
"operationId": "extract_document",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"description": "Multipart file upload request body schema for OpenAPI documentation.",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtractDocumentResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/forget": {
"post": {
"tags": [
"grains"
],
"operationId": "forget_grains",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForgetRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForgetResponse"
}
}
}
},
"400": {
"description": "At least one of user_id, subject, blob_hash, or hashes must be provided",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Grain not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/goals/{goal_hash}/delegate": {
"post": {
"tags": [
"goals"
],
"summary": "POST /api/memories/{memory_id}/goals/{goal_hash}/delegate",
"operationId": "session_delegate_goal",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "goal_hash",
"in": "path",
"description": "Goal grain hash",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DelegateGoalRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Goal delegated: {parent_hash: string, child_hash: string, delegate_to: string}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Goal not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/goals/{goal_hash}/state": {
"put": {
"tags": [
"goals"
],
"summary": "PUT /api/memories/{memory_id}/goals/{goal_hash}/state",
"operationId": "session_update_goal_state",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "goal_hash",
"in": "path",
"description": "Goal grain hash",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateGoalStateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Goal state updated: {old_hash: string, new_hash: string, state: string}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Goal not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Conflict — goal state already updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/grains": {
"get": {
"tags": [
"grains"
],
"operationId": "list_grains",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "subject",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "grain_type",
"in": "query",
"description": "Filter by grain type (e.g. \"fact\", \"event\", \"tool\"). Case-insensitive.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "offset",
"in": "query",
"description": "Pagination offset (legacy — prefer `after` cursor for infinite scroll).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "after",
"in": "query",
"description": "Cursor for keyset pagination (returned as `next_cursor` in previous response).",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "sort_by",
"in": "query",
"description": "Sort field: \"created_at\" (default), \"confidence\", \"grain_type\".",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "created_after",
"in": "query",
"description": "Filter grains created after this ISO timestamp.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "created_before",
"in": "query",
"description": "Filter grains created before this ISO timestamp.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppGrainsListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/grains/pull-stats/bulk": {
"post": {
"tags": [
"pull-stats"
],
"summary": "Bulk pull-stats lookup",
"description": "Issue #536 — returns pull-stats for up to 256 grain hashes in a single call. Hashes the caller cannot read or that reference unknown grains are silently omitted from the response map (matches bulk-get semantics).",
"operationId": "bulk_grain_pull_stats",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkPullStatsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Map of hash → pull-stats record (missing hashes silently dropped)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkPullStatsResponse"
}
}
}
},
"400": {
"description": "MEM-E131 too many hashes (> 256), or MEM-E132 malformed hash",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/grains/pull-stats/finalize-run": {
"post": {
"tags": [
"pull-stats"
],
"summary": "Finalize a run and update outcome-weighted pull scores",
"description": "Issue #536 — closes out a pull run by recording its outcome (`Confirmed` / `Failed` / `Skipped`, case-sensitive; `Skipped` is a no-op for the EWMA update) and applying an EWMA update to the `outcome_weighted_pull_score` of each participating grain. The `X-Idempotency-Key` header is REQUIRED for retry safety: a second call with the same key and identical body replays the cached response without re-applying the EWMA; a second call with the same key and a different body returns MEM-E137. Hashes that the caller cannot read or reference unknown grains are silently dropped from the update set.",
"operationId": "finalize_run_pull_stats",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Idempotency-Key",
"in": "header",
"description": "Required caller-supplied idempotency key. Same key + identical body → cached reply; same key + different body → MEM-E137 conflict.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FinalizeRunRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Run finalized — `updated` reports how many grains' EWMA scores changed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FinalizeRunResponse"
}
}
}
},
"400": {
"description": "MEM-E131 too many grain hashes (> 256), MEM-E132 malformed hash, MEM-E133 invalid run_id, MEM-E134 invalid outcome, or MEM-E136 missing X-Idempotency-Key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "MEM-E137 — same idempotency key already used for a different request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/grains/{hash}": {
"get": {
"tags": [
"grains"
],
"operationId": "get_grain",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hash",
"in": "path",
"description": "Grain blob hash",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppGrainDetailResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "SYS-E010 admission-shed — service overloaded; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/grains/{hash}/pull-stats": {
"get": {
"tags": [
"pull-stats"
],
"summary": "Per-grain pull telemetry",
"description": "Issue #536 — returns the pull-stats record for a single grain. Returns zeros for grains that have never been pulled (the grain itself must exist; otherwise MEM-E130 is returned to avoid an enumeration oracle).",
"operationId": "get_grain_pull_stats",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hash",
"in": "path",
"description": "Grain blob hash (hex-encoded SHA-256)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Pull-stats record for the grain",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PullStatsRecord"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "MEM-E130 — grain not found or not visible to caller",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/grains/{hash}/raw": {
"get": {
"tags": [
"grains"
],
"summary": "GET /api/memories/:id/grains/:hash/raw — download the raw .mg blob binary.",
"operationId": "get_grain_raw",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hash",
"in": "path",
"description": "Grain content-address hash (hex)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Raw .mg blob bytes",
"content": {
"application/octet-stream": {}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/graph": {
"get": {
"tags": [
"graph"
],
"operationId": "graph_subgraph_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "subject",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "depth",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "max_nodes",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "min_confidence",
"in": "query",
"required": false,
"schema": {
"type": [
"number",
"null"
],
"format": "double"
}
},
{
"name": "namespace",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "min_created_at",
"in": "query",
"description": "Minimum grain created_at (epoch ms). Grains older than this are excluded.",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
{
"name": "max_created_at",
"in": "query",
"description": "Maximum grain created_at (epoch ms). Grains newer than this are excluded.",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GraphResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/bind-tool": {
"post": {
"tags": [
"agents"
],
"summary": "POST /api/memories/{memory_id}/harnesses/{slug}/bind-tool",
"description": "Bind an Axtion tool to the harness by materializing an Tool grain under harnesses/<slug>/def. Body carries only the LLM-facing fields of the Axtion spec (param_schema, output_schema, examples) plus the opaque axtion_uri — the full endpoint and auth are fetched at invoke time.",
"operationId": "bind_tool",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"description": "Agent slug (kebab-case)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BindToolRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BindToolResponse"
}
}
}
},
"400": {
"description": "Invalid slug or missing axtion_uri (HRN-E003 / HRN-E005); schema-validator / PII rejections (MEM-E100..E106)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"403": {
"description": "Caller lacks write scope (AUT-E003); HIPAA-blocked client:// tool (HRN-E014)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found (MEM-E001)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"422": {
"description": "Request body failed JSON deserialization (missing required fields). axum default `Json<T>` extractor — plain-text body, not JSON."
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/chat": {
"post": {
"tags": [
"agents"
],
"summary": "POST /api/memories/{memory_id}/harnesses/{slug}/chat",
"description": "Run one agent turn. HIPAA + BAA gated. Returns the LLM response plus the resolved agent metadata (tool names, blocked tools, assemble params) so the app's Test tab can render a full trace.",
"operationId": "harness_chat",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"description": "Agent slug",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessChatRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessChatResponse"
}
}
}
},
"400": {
"description": "Missing Goal or invalid slug (HRN-E001 / HRN-E003)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"403": {
"description": "HIPAA + LLM provider has no BAA (HRN-E011)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found (MEM-E001)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"422": {
"description": "Request body failed JSON deserialization (missing required fields). axum default `Json<T>` extractor — plain-text body, not JSON."
},
"502": {
"description": "LLM provider error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/chat/resume": {
"post": {
"tags": [
"agents"
],
"summary": "POST /api/memories/{memory_id}/harnesses/{slug}/chat/resume",
"description": "Resume a paused Flow-A turn. The caller posts `tool_outputs` for every `pending_tool_calls` entry returned by the prior `requires_action` response. All outputs must be submitted in a single call. Returns another `requires_action` if the next iteration pauses again, or `completed` on EndTurn. A completed session is evicted from the SessionMap on EndTurn, so a subsequent resume of the same id yields `HRN-E015 / 404` (not 410) — the same opaque response as cross-principal and never-existed ids.",
"operationId": "chat_resume",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"description": "Harness slug",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatResumeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessChatResponse"
}
}
}
},
"400": {
"description": "Invalid slug (HRN-E003), missing outputs (HRN-E017), unknown tool_call_ids (HRN-E018), or schema violation (HRN-E019 — response carries optional `tool_call_id` + `detail`)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"403": {
"description": "Caller lacks write scope (AUT-E003)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"404": {
"description": "Memory (MEM-E001) or session (HRN-E015 — opaque: covers not-found, cross-principal, and completed cases) not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"410": {
"description": "Session TTL expired (HRN-E023). Note: completed sessions return 404 HRN-E015, not 410.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"413": {
"description": "Aggregate body (HRN-E024) or per-output (HRN-E019 detail=size, carries `tool_call_id` + `detail`) size cap exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"422": {
"description": "Request body failed JSON deserialization (missing required fields). axum default `Json<T>` extractor — plain-text body, not JSON."
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/chat/sessions/{session_id}": {
"delete": {
"tags": [
"agents"
],
"summary": "DELETE /api/memories/{memory_id}/harnesses/{slug}/chat/sessions/{session_id}",
"description": "Cancel a paused Flow-A session. Returns 204 on a successful cancel; returns 404 HRN-E015 (opaque, same wire bytes as cross-principal) when the session is not live for this caller — including when it never existed, was already cancelled, already completed, or belongs to a different principal. This endpoint is **not idempotent on the wire**: a second DELETE on the same session yields 404 HRN-E015 (not 204).",
"operationId": "chat_cancel",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"description": "Harness slug",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session id from prior suspend response",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Session cancelled"
},
"400": {
"description": "Invalid harness slug (HRN-E003)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"403": {
"description": "Caller lacks write scope (AUT-E003)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
},
"404": {
"description": "Memory (MEM-E001) or session (HRN-E015 — opaque; covers not-found, cross-principal, already-cancelled, and already-completed cases) not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/conversations": {
"get": {
"tags": [
"agents"
],
"summary": "GET /api/memories/{memory_id}/harnesses/{slug}/conversations",
"description": "List the calling user's harness conversations. Returns the sidebar summary rows (title, preview, updated_at) the UI needs to render the left rail without fanning out to the full event stream.",
"operationId": "list_harness_conversations",
"parameters": [
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max entries (default 100)",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessConversationListResponse"
}
}
}
},
"400": {
"description": "Invalid slug (HRN-E003)"
},
"404": {
"description": "Memory not found (MEM-E001)"
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/conversations/{conversation_id}": {
"delete": {
"tags": [
"agents"
],
"summary": "DELETE /api/memories/{memory_id}/harnesses/{slug}/conversations/{conv_id}",
"description": "Delete one harness conversation. Erases every grain in the conversation namespace, drops the session row, and submits a ClickHouse delete for the conversation's harness_feedback_events rows. Scoped to the calling user.",
"operationId": "delete_harness_conversation",
"parameters": [
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "conversation_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted (or no-op on unknown conv)"
},
"400": {
"description": "Invalid slug (HRN-E003)"
},
"404": {
"description": "Memory not found (MEM-E001)"
},
"503": {
"description": "ClickHouse feedback delete failed (HRN-E044)"
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/provision": {
"post": {
"tags": [
"agents"
],
"summary": "POST /api/memories/{memory_id}/harnesses/{slug}/provision",
"description": "Provision template grains (Goal) for a harness created from a template. Idempotent: calling twice returns the same goal_hash without writing duplicates.",
"operationId": "harness_provision",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"description": "Harness slug (kebab-case)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvisionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvisionResponse"
}
}
}
},
"400": {
"description": "Unknown template or display-only (HRN-E050 / HRN-E051)"
},
"404": {
"description": "Memory not found (MEM-E001)"
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/tool_callback_secret/rotate": {
"post": {
"tags": [
"agents"
],
"summary": "Rotate the per-harness `tool_callback_secret`. Generates a fresh\n32-byte base64url secret, persists it under the master-key envelope\nvia `harness_store::update`, emits a `ToolCallbackSecretRotated`\naudit row, and returns the new secret in clear.",
"description": "Rotate the per-harness HMAC secret used to verify worker-side tool-result callbacks. The new secret is returned exactly once. Subsequent rotations require the caller to prove possession of the current secret via an `If-Match` header carrying its `key_fingerprint`.",
"operationId": "rotate_tool_callback_secret",
"parameters": [
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "If-Match",
"in": "header",
"description": "key_fingerprint of the current secret; required when a secret already exists",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RotateCallbackSecretResponse"
}
}
}
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Caller lacks write scope on the memory (AUT-E003)"
},
"404": {
"description": "Memory or harness not found (MEM-E001 / HRN-E001)"
},
"412": {
"description": "If-Match key_fingerprint mismatch (HRN-E051)"
},
"428": {
"description": "If-Match required (HRN-E050)"
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/tools": {
"get": {
"tags": [
"agents"
],
"summary": "GET /api/memories/{memory_id}/harnesses/{slug}/tools",
"description": "List the bound tools for this harness — one entry per Tool grain under harnesses/<slug>/def (with read fallback to the legacy agents/<slug>/def per ADR-004). Each entry carries the LLM-facing fields plus the axtion_uri reference and an evaluated baa_ok flag reflecting the current memory's HIPAA posture.",
"operationId": "list_tools",
"parameters": [
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BoundToolsResponse"
}
}
}
},
"400": {
"description": "Invalid slug (HRN-E003)"
},
"404": {
"description": "Memory not found (MEM-E001)"
}
}
}
},
"/memories/{memory_id}/harnesses/{slug}/tools/invoke": {
"post": {
"tags": [
"actions"
],
"description": "Caller-driven (Flow B) tool execution. Resolves the named tool against the durable harness catalogue, optionally shadowed by per-request `extra_tools`, validates arguments against the Definition's `input_schema`, and dispatches to Axtion (server-side) or the caller (Flow B-CE). Returns the result + the hex hash of the persisted Execution Tool grain.",
"operationId": "invoke_tool",
"parameters": [
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvokeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvokeResponse"
}
}
}
},
"400": {
"description": "Invalid tool or arguments (HRN-E0xx / MEM-E10x)"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Blocked by harness policy (ACT-E004..E008)"
},
"404": {
"description": "Memory, harness, or tool not found (MEM-E001 / HRN-E001 / MEM-E109)"
},
"410": {
"description": "Session already completed (MEM-E112)"
},
"422": {
"description": "Overlay shadow rejected (ACT-E003)"
}
}
}
},
"/memories/{memory_id}/hooks": {
"get": {
"tags": [
"hooks"
],
"operationId": "list_hooks",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HooksListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"tags": [
"hooks"
],
"summary": "POST /api/memories/:id/hooks — create a hook.",
"operationId": "create_hook",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateHookRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HookResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/hooks/stats": {
"get": {
"tags": [
"hooks"
],
"summary": "GET /api/memories/:id/hooks/stats — hook system statistics.",
"operationId": "hook_stats",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HookStatsResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/hooks/{hook_id}": {
"delete": {
"tags": [
"hooks"
],
"operationId": "delete_hook",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "hook_id",
"in": "path",
"description": "Hook ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Hook deleted (idempotent — returns 200 even if the hook does not exist)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOkResponse"
}
}
}
},
"400": {
"description": "Invalid hook_id format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/import-document": {
"post": {
"tags": [
"import"
],
"summary": "POST /api/memories/:id/import-document",
"description": "Accepts a multipart/form-data upload with:\n - `file` — the document bytes (required)\n - `config` — optional JSON-serialized ImportConfigRequest\n\nParses the document, extracts text chunks, and writes each as an Episode grain.\nReturns ImportDocumentResponse with counts, hashes, and warnings.",
"operationId": "import_document",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"description": "Multipart file upload request body schema for OpenAPI documentation.",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportDocumentResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/import-file": {
"post": {
"tags": [
"import-export"
],
"operationId": "import_file",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"description": "Multipart file upload request body schema for OpenAPI documentation.",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportFileResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/knowledge-sources": {
"get": {
"tags": [
"knowledge-sources"
],
"summary": "`GET /api/memories/{memory_id}/knowledge-sources` — list KSes for the memory.",
"operationId": "list_knowledge_sources",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of knowledge sources for the memory",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSourcesListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
},
"post": {
"tags": [
"knowledge-sources"
],
"summary": "`POST /api/memories/{memory_id}/knowledge-sources` — create a draft KS.",
"description": "Body: `CreateKsRequest`. Returns the created `KnowledgeSource` (status = `Draft`).\nEnforces the per-memory cap (`MAX_KS_PER_MEMORY`) and per-scope file cap\n(`MAX_FILES_PER_KS`) at create time.",
"operationId": "create_knowledge_source",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateKsRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Draft KS created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSourceResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Per-memory cap exceeded (KS-E004)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error (KS-E001, KS-E002, KS-E003, KS-E013)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}": {
"get": {
"tags": [
"knowledge-sources"
],
"summary": "`GET /api/memories/{memory_id}/knowledge-sources/{ks_id}` — fetch a single KS.",
"operationId": "get_knowledge_source",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge source",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSourceResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Knowledge source not found (KS-E005)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
},
"put": {
"tags": [
"knowledge-sources"
],
"summary": "`PUT /api/memories/{memory_id}/knowledge-sources/{ks_id}` — rename / change scope / sync policy.",
"description": "Cannot change `connector_name`, `connection_id`, or terminal-state fields.\nTo change connection or connector, archive and re-create.",
"operationId": "update_knowledge_source",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateKsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Updated knowledge source",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeSourceResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Knowledge source not found (KS-E005)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "KS is archived (KS-E006)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error (KS-E001, KS-E013)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
},
"delete": {
"tags": [
"knowledge-sources"
],
"summary": "`DELETE /api/memories/{memory_id}/knowledge-sources/{ks_id}?mode=disconnect|forget|both`",
"operationId": "delete_knowledge_source",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "mode",
"in": "query",
"description": "Archive mode: disconnect (default), forget, or both. v0 supports disconnect only.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Knowledge source archived (response includes `grains_forgotten` for mode=forget|both)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArchiveResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Knowledge source or memory not found (KS-E005)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unknown archive mode (KS-E007)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Forget cascade failed (KS-E099)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}/browse": {
"post": {
"tags": [
"knowledge-sources"
],
"summary": "`POST /api/memories/{memory_id}/knowledge-sources/{ks_id}/browse` — list source files.",
"description": "Proxies to Axtion's `list_files` action for the bound connector. Returns a\npaginated `BrowseResult { items: BrowseItem[], next_cursor: Option<String> }`.\n\nv0: returns 503 if Axtion is not configured on this deployment (onprem\nfallback); v1+ wires every supported connector through this proxy.",
"operationId": "browse_knowledge_source",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Connector-specific browse params (e.g. {folder_id, cursor}). Forwarded to Axtion.",
"content": {
"application/json": {
"schema": {}
}
},
"required": true
},
"responses": {
"200": {
"description": "Paginated list of source items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowseResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Knowledge source not found (KS-E005)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"502": {
"description": "Axtion upstream error (KS-E010, KS-E011)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "Axtion not configured on this deployment (KS-E050)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}/changes": {
"post": {
"tags": [
"knowledge-sources"
],
"summary": "Public callback endpoint. Auth comes from the HMAC header — there is\nno Identity extractor here because Axtion is not a user.",
"operationId": "handle_callback",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Axtion change-event envelope (see crate::knowledge_sources::axtion_callback)",
"content": {
"application/json": {
"schema": {}
}
},
"required": true
},
"responses": {
"200": {
"description": "Callback accepted; per-file proposals persisted"
},
"401": {
"description": "HMAC mismatch (KS-E042)"
},
"404": {
"description": "Knowledge source not found (KS-E005)"
},
"422": {
"description": "Trigger ID does not match KS (KS-E042)"
}
}
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}/proposals": {
"get": {
"tags": [
"knowledge-sources"
],
"summary": "`GET /api/memories/{memory_id}/knowledge-sources/{ks_id}/proposals`",
"operationId": "list_proposals",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of pending and recent proposals",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProposalsListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Knowledge source not found (KS-E005)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}/proposals/{proposal_id}/approve": {
"post": {
"tags": [
"knowledge-sources"
],
"summary": "`POST /api/memories/{memory_id}/knowledge-sources/{ks_id}/proposals/{proposal_id}/approve`",
"description": "Runs the grain mutations stored in the proposal:\n1. CAS proposal status `pending|apply_failed → approving → applying → applied`.\n2. Execute Add → Supersede → Forget actions in order (per §10.3 sharp rule).\n3. Emit `KnowledgeSourceManuallyApproved` audit on the hash chain.\n\nIdempotent under double-click — second caller sees CAS conflict and gets `KS-E020`.",
"operationId": "approve_proposal",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "proposal_id",
"in": "path",
"description": "Proposal identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Proposal applied (or partial — see errors[])",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApproveResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Proposal not found (KS-E040)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Proposal already approving / terminal (KS-E020 / KS-E041)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Apply failed — see errors[] (KS-E021)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}/proposals/{proposal_id}/reject": {
"post": {
"tags": [
"knowledge-sources"
],
"summary": "`POST /api/memories/{memory_id}/knowledge-sources/{ks_id}/proposals/{proposal_id}/reject`",
"description": "CAS proposal status `pending|apply_failed → rejected`. No grain mutation runs.\nEmits `KnowledgeSourceProposalRejected` audit.",
"operationId": "reject_proposal_route",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "proposal_id",
"in": "path",
"description": "Proposal identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Proposal rejected",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RejectResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Proposal not found (KS-E040)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Proposal already terminal (KS-E041)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/knowledge-sources/{ks_id}/sync": {
"post": {
"tags": [
"knowledge-sources"
],
"summary": "`POST /api/memories/{memory_id}/knowledge-sources/{ks_id}/sync` — manual sync trigger.",
"description": "v0: marks the KS as `indexing` and returns a queued response. The actual\nfetch + parse + grain-create pipeline lands in v0.1 (wires Axtion download\nto the existing async-import pipeline). The per-file orchestration follows\nthe contract in `docs/work/areev-architect/knowledge-sources-design.md`.",
"operationId": "sync_knowledge_source",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory identifier",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "ks_id",
"in": "path",
"description": "Knowledge source identifier",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Sync queued; per-file orchestration runs in the background",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Knowledge source not found (KS-E005)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "KS is archived (KS-E006)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Empty scope (KS-E008)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/memories/{memory_id}/metrics/{metric_id}/series": {
"get": {
"tags": [
"health-dashboard"
],
"operationId": "metric_series_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "metric_id",
"in": "path",
"description": "Metric ID (allowlisted)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"description": "Time range: 1m, 5m, 1h, 24h",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metric time series"
},
"404": {
"description": "Unknown metric ID"
}
}
}
},
"/memories/{memory_id}/namespaces/{namespace}": {
"delete": {
"tags": [
"namespaces"
],
"operationId": "purge_namespace_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "namespace",
"in": "path",
"description": "Namespace name to purge",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "dry_run",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "force",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PurgeNamespaceBody"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Purge succeeded (or dry-run completed, or namespace was already absent)"
},
"400": {
"description": "Reserved namespace (MEM-E113) or invalid namespace name (MEM-E117)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Permission denied (MEM-E115)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Consent / restricted grains require force (MEM-E114) or in-flight conflict (MEM-E116)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/policy": {
"get": {
"tags": [
"policy"
],
"operationId": "get_policy",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyAppResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": [
"policy"
],
"operationId": "modify_policy",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyModifyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Policy updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyModifyResponse"
}
}
}
},
"400": {
"description": "Invalid policy name or downgrade without reason",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/policy/enforce": {
"post": {
"tags": [
"policy"
],
"summary": "POST /memories/{id}/policy/enforce — run enforcement for a specific control.",
"description": "Returns SSE stream with progress events for long-running operations (encryption, PII scan),\nor immediate JSON for quick operations (TTL count, consent status).",
"operationId": "enforce_policy",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyEnforceRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Enforcement result"
},
"400": {
"description": "Invalid control",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/policy/enforcement-status": {
"get": {
"tags": [
"policy"
],
"summary": "GET /memories/{id}/policy/enforcement-status — stateless check of what enforcement is needed.",
"operationId": "enforcement_status",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Enforcement actions needed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnforcementStatusResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/policy/residency": {
"put": {
"tags": [
"policy"
],
"summary": "`PUT /memories/{memory_id}/policy/residency` — set the per-memory\ndata-residency override (issue #570, PDPA M2). Admin-scoped. Persists onto\nthe policy seal and hot-reloads the policy engine so subsequent writes to a\ndisallowed-region cell are refused with `PDP-E001` (the gate compares\n`allowed_regions` against the cell's `AREEV_REGION`).",
"operationId": "set_policy_residency",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyResidencyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Residency override set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyResidencyResponse"
}
}
}
},
"400": {
"description": "Invalid enforcement value",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"policy"
],
"summary": "`DELETE /memories/{memory_id}/policy/residency` — clear the residency\noverride (issue #570). Admin-scoped.",
"operationId": "delete_policy_residency",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Residency override cleared",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyResidencyResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/policy/resolved": {
"get": {
"tags": [
"policy"
],
"operationId": "get_policy_resolved",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Resolved policy projection",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyResolvedResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found or no policy configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/policy/simulate": {
"post": {
"tags": [
"policy"
],
"operationId": "policy_simulate",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicySimulateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicySimulationResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/predicate-hint": {
"post": {
"tags": [
"intelligence"
],
"summary": "POST /api/memories/{memory_id}/predicate-hint — ingest a single cardinality\nhint. Tier-gated by `adaptive_vocabulary` (Free tier rejected at the\nEntitlementLayer). Returns the outcome ({Accepted, RateLimited,\nStaticOverride, InvalidInput}) so the extractor can adjust.",
"operationId": "predicate_hint_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PredicateHintRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Hint outcome",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Tier does not include adaptive_vocabulary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/predicate-registry": {
"get": {
"tags": [
"intelligence"
],
"summary": "GET /api/memories/{memory_id}/predicate-registry — enumerate the merged\n(static + learned) predicate cardinality registry for this memory. Used\nby the App graph view to render functional vs non-functional edges with\ndistinct styling, and by operators to inspect what the memory has\nlearned. Read-only; not tier-gated (visibility is fine on every tier).",
"operationId": "predicate_registry_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Merged predicate registry",
"content": {
"application/json": {
"schema": {}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/provenance": {
"get": {
"tags": [
"provenance"
],
"summary": "GET /api/memories/{memory_id}/provenance?namespace=&from=&to=&limit=\nList provenance records with optional filtering.",
"operationId": "list_provenance_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "namespace",
"in": "query",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
{
"name": "to",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
{
"name": "enrich",
"in": "query",
"description": "When true, hydrate each returned_hash with grain type + content summary.\nGrains are fetched from cache/disk on the fly (not stored in provenance).",
"required": false,
"schema": {
"type": [
"boolean",
"null"
]
}
},
{
"name": "min_results",
"in": "query",
"description": "Exclude recalls whose `result_count` is below this threshold. Default: 0 (no filter).\nPass `1` to hide empty recalls (e.g. chat auto-recalls that returned no matches).",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvenanceListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/provenance/summary": {
"get": {
"tags": [
"provenance"
],
"summary": "GET /api/memories/:id/provenance/summary — aggregate provenance statistics.",
"operationId": "provenance_summary",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProvenanceSummaryResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/provenance/{recall_id}": {
"get": {
"tags": [
"provenance"
],
"summary": "GET /api/memories/{memory_id}/provenance/{recall_id}\nRetrieve a single provenance record by its recall_id hash.",
"operationId": "get_provenance_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "recall_id",
"in": "path",
"description": "Recall ID hash",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Provenance record with scoring signals, source grains, and retrieval metadata",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Provenance record not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/recall": {
"post": {
"tags": [
"grains"
],
"operationId": "recall_grains",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Areev-Run-Id",
"in": "header",
"description": "Optional caller-supplied run identifier (issue #536). 1..=128 bytes, no ASCII control chars. Tags this recall in per-grain pull telemetry so distinct_run_pull_count and outcome_weighted_pull_score can be populated. Returns MEM-E136 if malformed.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallAppRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallResponse"
}
}
}
},
"400": {
"description": "Invalid request body — malformed JSON or `limit` is 0",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Schema or validation error — body contains an unknown field (e.g. `grain_types` instead of `grain_type`), is missing a required field, OR no narrowing filter was provided (any of: query, subject, relation, object, subject_in, relation_in, object_in, namespace, scope_path, entity, tags, embedding, temporal_expr, time_range_start/end, target_date, user_id)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "SYS-E010 admission-shed — service overloaded; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/recall-chain": {
"post": {
"tags": [
"grains"
],
"summary": "Multi-hop recall chain",
"description": "FR-A006: Decompose a complex question into sub-queries via an LLM, execute each sub-query independently, then merge and deduplicate the results. Requires an LLM provider configured in the provider registry (role: chat). Without an LLM, falls back to a single sub-query using the original question.",
"operationId": "recall_chain",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Areev-Run-Id",
"in": "header",
"description": "Optional caller-supplied run identifier (issue #536). 1..=128 bytes, no ASCII control chars. Tags each sub-query recall in per-grain pull telemetry. Returns MEM-E136 if malformed.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallChainAppRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Merged recall results with sub-query breakdown",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallChainResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error — empty query",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/recent-events": {
"get": {
"tags": [
"health-dashboard"
],
"operationId": "events_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max events (default 8, max 50)",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Recent activity events"
}
}
}
},
"/memories/{memory_id}/remember": {
"post": {
"tags": [
"grains"
],
"summary": "POST /api/memories/{memory_id}/remember — Ingest natural language text as memory.",
"description": "Ingests natural language text as memory (Observation grain async, Facts sync). When `namespace` is unspecified, the server picks an existing namespace if any exist; the namespace cap does not apply.",
"operationId": "remember_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppRememberRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Text accepted for memory ingestion",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppRememberResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "HIPAA policy violation or missing user_id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/retention/enforce": {
"post": {
"tags": [
"compliance"
],
"summary": "POST /api/memories/:id/retention/enforce — trigger retention enforcement.\nScans all grains in the memory and deletes those whose TTL has elapsed.\nSkips SOX-policy memories (immutability constraint). Requires write permission.",
"operationId": "retention_enforce",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "dry_run",
"in": "query",
"description": "If true, preview what would be deleted without actually deleting.",
"required": false,
"schema": {
"type": [
"boolean",
"null"
]
}
},
{
"name": "namespace",
"in": "query",
"description": "If set, enforce TTL only within this namespace. When omitted, enforces across all namespaces.",
"required": false,
"schema": {
"type": [
"string",
"null"
]
}
}
],
"responses": {
"200": {
"description": "Retention enforcement result: {status: string, deleted: integer, message: string}",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"deleted": 3,
"message": "Retention enforcement complete: 3 grain(s) expired and deleted.",
"status": "ok"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient permissions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/retention/status": {
"get": {
"tags": [
"compliance"
],
"summary": "GET /api/memories/:id/retention/status — per-namespace retention status.",
"operationId": "retention_status",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionStatusResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/scope-erase": {
"post": {
"tags": [
"scoped"
],
"operationId": "scope_erase",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScopeEraseRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Scope erasure proof",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScopeErasureProofResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Scope not found or empty",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScopeErasureProofResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/scope-tree": {
"get": {
"tags": [
"scoped"
],
"operationId": "get_scope_tree",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Scope tree structure with nested scopes and grain counts",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": [
"scoped"
],
"operationId": "set_scope_tree",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScopeTree"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Scope tree updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOkResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Invalid scope tree format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"scoped"
],
"operationId": "delete_scope_tree",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Scope tree deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOkResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/bootstrap": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/bootstrap",
"operationId": "session_bootstrap",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "recent_tools_limit",
"in": "query",
"description": "Maximum number of recent actions to include (default: 20).",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Bootstrap data for the session. Returns {session_id: string, state: null|object, active_goals: array, active_goals_count: int, recent_tools: array, recent_tools_count: int}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/consolidate": {
"post": {
"tags": [
"intelligence"
],
"summary": "POST /api/memories/{memory_id}/sessions/{session_id}/consolidate",
"operationId": "session_consolidate",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsolidateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Consolidation result with merged grains and statistics",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/context": {
"get": {
"tags": [
"intelligence"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/context?token_budget=4096",
"operationId": "session_compile_context",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "token_budget",
"in": "query",
"description": "Token budget (default: 4096).",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Compiled context for the session. Returns {session_id: string, state: object or null, goals: array, tools: array, facts: array, estimated_tokens: int, token_budget: int, truncated: bool}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/goals": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/goals",
"operationId": "session_active_goals",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Active goals for the session. Returns {count: int, goals: array[grain objects]}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/goals/blocked": {
"get": {
"tags": [
"goals"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/goals/blocked",
"operationId": "session_blocked_goals",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Blocked goals: {blocked_goals: array of goal grains, count: integer}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/goals/create": {
"post": {
"tags": [
"goals"
],
"summary": "POST /api/memories/{memory_id}/sessions/{session_id}/goals/create",
"operationId": "session_create_goal",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGoalRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Goal created, returns grain hash",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HashResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/goals/tree": {
"get": {
"tags": [
"goals"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/goals/tree",
"operationId": "session_goal_tree",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Goal tree: {total_goals: integer, roots: array of goal tree nodes}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/state": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/state",
"operationId": "session_latest_state",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Latest state grain for this session, or null if no state exists",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/tools": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/tools",
"operationId": "session_recent_tools",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "path",
"required": true,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Recent tools for the session. Returns {tools: array[grain objects], count: int}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/tools/chain/{task_id}": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/tools/chain/{task_id}",
"operationId": "session_tool_chain",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "task_id",
"in": "path",
"description": "Task ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Tool chain: {chain: array of tool grains, count: integer}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/tools/failed": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/tools/failed",
"operationId": "session_failed_tools",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "since",
"in": "path",
"required": true,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Failed tools in the session. Returns {failed_tools: array[grain objects], count: int}. Optional query param: since (epoch ms unix timestamp)",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/sessions/{session_id}/tools/summary": {
"get": {
"tags": [
"sessions"
],
"summary": "GET /api/memories/{memory_id}/sessions/{session_id}/tools/summary",
"operationId": "session_tool_summary",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "session_id",
"in": "path",
"description": "Session ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Tool summary with total, success/error counts, and per-tool breakdown",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/states/diff": {
"post": {
"tags": [
"sessions"
],
"summary": "POST /api/memories/{memory_id}/states/diff",
"operationId": "session_diff_states",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiffStatesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "State diff: {old_hash, new_hash, added: array, removed: array, changed: array of {key, old_value, new_value}, unchanged: array}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/stats": {
"get": {
"tags": [
"stats"
],
"operationId": "memory_stats",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppStatsResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/stats/history": {
"get": {
"tags": [
"stats"
],
"operationId": "stats_history",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "days",
"in": "query",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatsHistoryResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/supersede": {
"post": {
"tags": [
"grains"
],
"operationId": "supersede_grain",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupersedeAppRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SupersedeAppResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Supersession conflict — grain already superseded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "SYS-E010 admission-shed — service overloaded; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/top-writers": {
"get": {
"tags": [
"health-dashboard"
],
"operationId": "top_writers_handler",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max writers (default 10, max 50)",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Top writers by write count"
}
}
}
},
"/memories/{memory_id}/verify/latest": {
"get": {
"tags": [
"compliance"
],
"operationId": "verify_latest",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerificationLatestResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/memories/{memory_id}/verify/run": {
"post": {
"tags": [
"compliance"
],
"operationId": "verify_run",
"parameters": [
{
"name": "memory_id",
"in": "path",
"description": "Memory ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyRunRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerificationRunResponse"
}
}
}
},
"400": {
"description": "Invalid request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Memory not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/models": {
"get": {
"tags": [
"providers"
],
"summary": "GET /api/models — unified list of available models across all providers.\nSupports ?capability=chat filter.",
"operationId": "list_models",
"parameters": [
{
"name": "capability",
"in": "query",
"description": "Filter by capability: chat, chat_tool_use, rerank, import, embed",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/preferences": {
"get": {
"tags": [
"preferences"
],
"summary": "GET /api/preferences — all preferences for the authenticated user.",
"operationId": "get_preferences",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferencesResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": [
"preferences"
],
"summary": "PUT /api/preferences — set/update multiple preferences.",
"operationId": "update_preferences",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePreferencesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferencesResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/preferences/{key}": {
"get": {
"tags": [
"preferences"
],
"summary": "GET /api/preferences/{key} — get a single preference.",
"operationId": "get_preference",
"parameters": [
{
"name": "key",
"in": "path",
"description": "Preference key",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferenceResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"preferences"
],
"summary": "DELETE /api/preferences/{key} — delete a single preference.",
"operationId": "delete_preference",
"parameters": [
{
"name": "key",
"in": "path",
"description": "Preference key",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOkResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings": {
"get": {
"tags": [
"admin"
],
"summary": "GET /api/settings — requires admin scope.",
"operationId": "get_settings",
"responses": {
"200": {
"description": "Current server settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsResponse"
}
}
}
},
"403": {
"description": "Admin scope required"
}
},
"security": [
{
"api_key": []
}
]
}
},
"/settings/llm": {
"get": {
"tags": [
"llm"
],
"summary": "GET /api/settings/llm — return current LLM provider settings (legacy, delegates to provider registry).",
"operationId": "get_llm_settings",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LlmSettingsResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": [
"llm"
],
"description": "Update LLM provider settings. Requires admin scope when authentication is enabled. Changes affect all LLM-powered features (chat, import analysis, reranking).",
"operationId": "update_llm_settings",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLlmSettingsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Updated settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LlmSettingsResponse"
}
}
}
},
"403": {
"description": "Admin scope required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"api_key": []
},
{
"bearer": []
}
]
}
},
"/settings/model-assignments": {
"get": {
"tags": [
"providers"
],
"summary": "GET /api/settings/model-assignments — current role-to-model mappings.",
"operationId": "get_model_assignments",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelAssignmentsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"put": {
"tags": [
"providers"
],
"summary": "PUT /api/settings/model-assignments — update role-to-model mappings.",
"operationId": "update_model_assignments",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateModelAssignmentsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelAssignmentsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings/ner/status": {
"get": {
"tags": [
"compliance"
],
"summary": "GET /api/settings/ner/status — NER model availability status.",
"operationId": "ner_status",
"responses": {
"200": {
"description": "NER status: {ner_available: boolean, model_loaded: boolean, model_type: string, status: string}",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/settings/provider-policy": {
"get": {
"tags": [
"providers"
],
"summary": "GET /api/settings/provider-policy — current provider policy.",
"operationId": "provider_policy",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProviderPolicyResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings/providers": {
"get": {
"tags": [
"providers"
],
"summary": "GET /api/settings/providers — list all providers (catalog + custom).",
"operationId": "list_providers",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProviderListResponse"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings/providers/{provider_id}": {
"put": {
"tags": [
"providers"
],
"summary": "PUT /api/settings/providers/{provider_id} — configure a catalog provider or update a custom one.",
"operationId": "upsert_provider",
"parameters": [
{
"name": "provider_id",
"in": "path",
"description": "Provider ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpsertProviderRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Provider updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"providers"
],
"summary": "DELETE /api/settings/providers/{provider_id} — remove a provider.",
"operationId": "delete_provider",
"parameters": [
{
"name": "provider_id",
"in": "path",
"description": "Provider ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOkResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Provider referenced by model assignments",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings/providers/{provider_id}/models": {
"get": {
"tags": [
"providers"
],
"summary": "GET /api/settings/providers/{provider_id}/models — discover models from a specific provider.",
"operationId": "provider_models",
"parameters": [
{
"name": "provider_id",
"in": "path",
"description": "Provider ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProviderModelsResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings/providers/{provider_id}/test": {
"post": {
"tags": [
"providers"
],
"summary": "POST /api/settings/providers/{provider_id}/test — test provider connection.",
"operationId": "test_provider",
"parameters": [
{
"name": "provider_id",
"in": "path",
"description": "Provider ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionTestResponse"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/settings/sso": {
"put": {
"tags": [
"admin"
],
"summary": "PUT /api/settings/sso — requires admin scope.\nSaves SSO config to AdminStore. Requires server restart to take effect.",
"operationId": "update_sso",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSsoRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "SSO configuration saved (restart required)"
},
"403": {
"description": "Admin scope required"
},
"422": {
"description": "Validation error"
}
},
"security": [
{
"api_key": []
}
]
}
},
"/team": {
"get": {
"tags": [
"admin"
],
"summary": "GET /api/team — requires admin scope.\nCombines API keys from ApiKeyStore with team metadata from AdminStore.",
"operationId": "get_team",
"responses": {
"200": {
"description": "Team members and auth mode",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TeamResponse"
}
}
}
},
"403": {
"description": "Admin scope required"
}
},
"security": [
{
"api_key": []
}
]
}
},
"/team/{key_id}": {
"put": {
"tags": [
"admin"
],
"summary": "PUT /api/team/{key_id} — requires admin scope.\nUpdates display name and role metadata for an API key.",
"operationId": "update_team_member",
"parameters": [
{
"name": "key_id",
"in": "path",
"description": "API key ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTeamMemberRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Team member updated"
},
"403": {
"description": "Admin scope required"
},
"404": {
"description": "Key not found"
}
},
"security": [
{
"api_key": []
}
]
}
},
"/triggers/tool-result/callback": {
"post": {
"tags": [
"triggers"
],
"summary": "`POST /api/triggers/tool-result/callback`",
"description": "Worker-side resolver for in-flight async tool calls. Verifies the HMAC signature against the harness's `tool_callback_secret`, dedups on `correlation_id`, looks up the matching Pending Tool grain, and supersedes it with a Completed or Failed Execution grain. Request body MUST be JSON and signature MUST be carried in `X-Axtion-Signature: sha256=<hex>` with a Unix-seconds `X-Axtion-Timestamp` header (±5 minute window). The header names are `X-Axtion-*` for parity with the existing KS-auth sink — the verifier is shared across sinks.",
"operationId": "handle_tool_result_callback",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResultCallback"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallbackAck"
}
}
}
},
"401": {
"description": "HMAC verification failed (TRG-E001)"
},
"404": {
"description": "Unknown correlation_id or harness mismatch (TRG-E005)"
},
"422": {
"description": "Malformed JSON body (FMT-E001)"
}
}
}
},
"/v1/tools/parse": {
"post": {
"tags": [
"actions"
],
"description": "Stateless 5-format parser for LLM tool-call output. Accepts a wire format identifier + raw provider output, returns structured tool-call records plus any non-fatal parse errors. Malformed input returns HTTP 200 with errors populated — the caller decides whether to retry or abort.",
"operationId": "parse_tool",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParseRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParseResponse"
}
}
}
},
"400": {
"description": "Unknown format (MEM-E107) or raw_output above 1 MB cap (MEM-E108)"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Missing read/write scope (AUT-E003)"
}
}
}
}
},
"components": {
"schemas": {
"AccumulateAppRequest": {
"type": "object",
"description": "Accumulate request body.",
"required": [
"grain_type",
"target",
"add",
"reason"
],
"properties": {
"add": {
"type": "object",
"description": "Numeric deltas: { \"field\": delta, ... }",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
},
"grain_type": {
"type": "string",
"description": "Grain type (e.g. \"fact\")."
},
"reason": {
"type": "string",
"description": "Reason for the accumulation."
},
"set": {
"type": [
"object",
"null"
],
"description": "Optional last-writer-wins replacements.",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
},
"target": {
"type": "object",
"description": "Target: { \"kind\": \"tip_resolved\", \"subject\": \"...\", \"relation\": \"...\" } or { \"kind\": \"hash\", \"hash\": \"...\" }",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
}
}
},
"AccumulateAppResponse": {
"type": "object",
"description": "Accumulate response body.",
"required": [
"old_hash",
"new_hash",
"status",
"deltas"
],
"properties": {
"deltas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccumulateDelta"
},
"description": "Applied delta details."
},
"new_hash": {
"type": "string",
"description": "Hash of the new (post-accumulation) grain."
},
"old_hash": {
"type": "string",
"description": "Hash of the old (pre-accumulation) grain."
},
"status": {
"type": "string",
"description": "Status indicator."
}
}
},
"AccumulateDelta": {
"type": "object",
"description": "A single applied delta in an accumulation.",
"required": [
"field",
"old_value",
"new_value"
],
"properties": {
"field": {
"type": "string",
"description": "Field name."
},
"new_value": {
"type": "number",
"format": "double",
"description": "Value after accumulation."
},
"old_value": {
"type": "number",
"format": "double",
"description": "Value before accumulation."
}
}
},
"AddGrainRequest": {
"type": "object",
"description": "Request body for adding a grain.",
"required": [
"grain_type",
"fields"
],
"properties": {
"fields": {
"type": "object",
"description": "Key-value fields for the grain"
},
"grain_type": {
"type": "string",
"description": "Grain type: \"fact\", \"event\", \"state\", \"workflow\", \"tool\", \"observation\", \"goal\", \"reasoning\", \"consensus\", \"consent\", \"skill\""
}
}
},
"AgentIdentitiesListResponse": {
"type": "object",
"description": "List of agent identities.",
"required": [
"identities",
"count"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"identities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentIdentityResponse"
}
}
}
},
"AgentIdentityResponse": {
"type": "object",
"description": "An agent identity with permissions and status.",
"required": [
"agent_id",
"status",
"delegated_by",
"registered",
"permissions",
"namespaces",
"total_events"
],
"properties": {
"agent_id": {
"type": "string"
},
"delegated_by": {
"type": "string"
},
"last_active": {
"type": [
"string",
"null"
]
},
"namespaces": {
"type": "array",
"items": {
"type": "string"
}
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"registered": {
"type": "string"
},
"status": {
"type": "string",
"description": "Agent status: \"active\", \"paused\", or \"deactivated\"."
},
"total_events": {
"type": "integer",
"minimum": 0
}
}
},
"AlertItem": {
"type": "object",
"description": "A single alert item surfaced on the Home (Command Center) page.",
"required": [
"id",
"severity",
"category",
"title",
"description",
"action",
"route"
],
"properties": {
"action": {
"type": "string",
"description": "Suggested CTA label (e.g. \"Fix\", \"Resolve\", \"Review\")."
},
"category": {
"type": "string",
"description": "Category: \"Compliance\", \"Security\", \"Intelligence\", \"Retention\", \"Operations\"."
},
"description": {
"type": "string",
"description": "Detailed description of the alert."
},
"detail": {
"type": [
"object",
"null"
],
"description": "Optional context-specific detail data for inline expansion."
},
"id": {
"type": "string",
"description": "Unique alert identifier (e.g. \"compliance:enc_at_rest\")."
},
"route": {
"type": "string",
"description": "Frontend route to navigate to (e.g. \"verify\", \"policies\", \"intelligence\")."
},
"severity": {
"type": "string",
"description": "Severity: \"critical\" or \"warning\"."
},
"title": {
"type": "string",
"description": "Short human-readable title."
}
}
},
"AlertsQuery": {
"type": "object",
"description": "Query parameters for the alerts endpoint.",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"description": "Maximum alerts to return (1–100, default 20).",
"minimum": 0
}
}
},
"AlertsResponse": {
"type": "object",
"description": "Response for `GET /api/memories/:id/alerts`.",
"required": [
"alerts",
"generated_at",
"source_counts",
"total_count",
"truncated",
"compliance"
],
"properties": {
"alerts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AlertItem"
}
},
"compliance": {
"$ref": "#/components/schemas/ComplianceVerification",
"description": "Freshness state of the compliance verification data included in\nthis response. Compliance checks can take 10+ seconds on large\nencrypted memories, so the homepage serves cached/background results\ninstead of blocking. The verify screen (`POST /verify/run`) always\nruns a full synchronous verification."
},
"generated_at": {
"type": "string"
},
"source_counts": {
"$ref": "#/components/schemas/SourceCounts"
},
"total_count": {
"type": "integer",
"minimum": 0
},
"truncated": {
"type": "boolean"
}
}
},
"AppAddGrainRequest": {
"type": "object",
"description": "Add grain request body (App format).\n\nFor fact grains (default), `subject`, `relation`, and `object` are required.\nFor other grain types, pass grain-type-specific fields (e.g. `content` for event,\n`description` for goal). Any unrecognized fields are forwarded via `fields`.\n\n**Consent grains** require both `subject_did` and `user_id` fields. These must be\nprovided in the `fields` map (or as top-level flattened keys). Omitting either\nwill result in a 422 validation error.\n\n## Body shape canonicalization\n\nCallers may send either of two equivalent shapes; the handler accepts both:\n\n```json\n// 1. Flat (historical /add shape)\n{ \"grain_type\": \"fact\", \"subject\": \"ada\", \"relation\": \"role\", \"object\": \"engineer\" }\n\n// 2. Nested (matches /batch-add and MCP `areev_add`)\n{ \"grain_type\": \"fact\", \"fields\": { \"subject\": \"ada\", \"relation\": \"role\", \"object\": \"engineer\" } }\n```\n\nOn deserialization, if the body contains a `fields` object, its entries are hoisted\nto the top level. Explicit top-level keys take precedence over any same-named key\nnested under `fields`. Non-object values for `fields` (a mis-typed primitive) are\ndropped — keep the grain-type-specific keys at top level or inside a `fields`\nobject, never both conflicting. This canonicalization is intentional so SDK and\nMCP callers can reuse the same request shape they use elsewhere.",
"required": [
"fields"
],
"properties": {
"auto_relate": {
"type": [
"boolean",
"null"
],
"description": "Auto-detect updates/extends relationships with existing grains."
},
"confidence": {
"type": [
"number",
"null"
],
"format": "double"
},
"created_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Explicit timestamp in milliseconds since epoch."
},
"embedding_text": {
"type": [
"string",
"null"
],
"description": "Custom embedding text for vector index (overrides default subject+relation+object)."
},
"extract_event_date": {
"type": [
"boolean",
"null"
],
"description": "Extract temporal references from content and auto-populate `valid_from`."
},
"extract_memories": {
"type": [
"boolean",
"null"
],
"description": "Decompose content into atomic Fact grains linked via `derived_from`.\nRequires a `memory_extractor` function on AreevBuilder. No-op without one."
},
"fields": {
"type": "object",
"description": "Additional grain-type-specific fields (e.g. `content`, `description`, `tool_name`)."
},
"grain_type": {
"type": [
"string",
"null"
],
"description": "Grain type (default: \"fact\"). Must be one of the 11 OMS grain types."
},
"namespace": {
"type": [
"string",
"null"
]
},
"object": {
"type": [
"string",
"null"
]
},
"relation": {
"type": [
"string",
"null"
]
},
"source_type": {
"type": [
"string",
"null"
],
"description": "Source attribution (e.g. \"user\", \"assistant\")."
},
"subject": {
"type": [
"string",
"null"
]
},
"sync": {
"type": [
"boolean",
"null"
],
"description": "Force immediate commit (bypass write batch buffer)."
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
}
}
},
"AppAddGrainResponse": {
"type": "object",
"description": "Add grain response (App format).",
"required": [
"blob_hash",
"status"
],
"properties": {
"blob_hash": {
"type": "string"
},
"extracted_memories": {
"type": "integer",
"description": "Number of Fact grains extracted from the source content via `extract_memories`.\nZero when extraction was not requested or when extraction failed.",
"minimum": 0
},
"status": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"AppConfigResponse": {
"type": "object",
"description": "App configuration response — returned by GET /api/config.\n\nTells the Angular app what deployment mode it is running in so it can\nadapt navigation, auth flow, and feature visibility without a login round-trip.\nThis endpoint is public (no auth required).",
"required": [
"mode",
"auth",
"auth_anonymous",
"distributed",
"version",
"provider_policy"
],
"properties": {
"auth": {
"type": "string",
"description": "Active auth mode: \"api-key\" | \"oidc\" | \"composite\"."
},
"auth_anonymous": {
"type": "boolean",
"description": "Always false — anonymous access is not supported."
},
"cell_id": {
"type": [
"string",
"null"
],
"description": "Cell identifier within a region (PM-PASSPORT). None in single-cell mode."
},
"distributed": {
"type": "boolean",
"description": "True when compiled with the `distributed` feature and the cluster is active."
},
"mode": {
"type": "string",
"description": "Deployment mode: \"self-hosted\" or \"cloud\".\nAlways \"self-hosted\" for the open-source app; cloud deployments set \"cloud\"."
},
"node_id": {
"type": [
"string",
"null"
],
"description": "Raft node ID when distributed, null otherwise."
},
"oauth_providers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OAuthProviderInfo"
},
"description": "Available OAuth providers with their public client IDs.\nEmpty when auth mode doesn't support OAuth."
},
"passport_enabled": {
"type": "boolean",
"description": "Whether Passport Model cross-region identity is active (PM-PASSPORT)."
},
"provider_policy": {
"type": "string",
"description": "Provider policy: \"managed\" (cloud/dev — platform controls providers)\nor \"configurable\" (self-hosted — users manage providers)."
},
"region": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/RegionInfo",
"description": "Region info for this node. Populated in cloud mode from AREEV_REGION env var."
}
]
},
"regions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RegionInfo"
},
"description": "Available regions the org can use. Populated in cloud mode from AREEV_REGIONS env var."
},
"version": {
"type": "string",
"description": "Areev server version (from CARGO_PKG_VERSION)."
}
}
},
"AppGrainDetailResponse": {
"type": "object",
"description": "Detail view for a single grain.",
"required": [
"blob_hash",
"grain",
"provenance",
"supersession_chain",
"contradictions",
"feedback_history",
"access_log",
"consolidation_path",
"audit_entries"
],
"properties": {
"access_log": {
"type": "array",
"items": {
"type": "object"
}
},
"audit_entries": {
"type": "array",
"items": {
"type": "object"
}
},
"blob_hash": {
"type": "string"
},
"consolidation_path": {
"type": "array",
"items": {
"type": "object"
}
},
"contradictions": {
"type": "array",
"items": {
"type": "object"
}
},
"feedback_history": {
"type": "array",
"items": {
"type": "object"
}
},
"grain": {
"type": "object"
},
"provenance": {
"type": "array",
"items": {
"type": "object"
}
},
"supersession_chain": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"AppGrainResponse": {
"type": "object",
"description": "A grain in App format.",
"required": [
"subject",
"relation",
"object",
"confidence",
"blob_hash",
"tags",
"grain_type"
],
"properties": {
"blob_hash": {
"type": "string"
},
"confidence": {
"type": "number",
"format": "double"
},
"created_at": {
"type": [
"string",
"null"
]
},
"fields": {
"type": "object",
"description": "All grain fields (enables type-specific rendering for non-Fact grain types)."
},
"grain_type": {
"type": "string"
},
"namespace": {
"type": [
"string",
"null"
]
},
"object": {
"type": "string"
},
"relation": {
"type": "string"
},
"subject": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"temporal_type": {
"type": [
"string",
"null"
]
}
}
},
"AppGrainsListResponse": {
"type": "object",
"description": "Paginated grains response.",
"required": [
"grains",
"count",
"total",
"has_more"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"grains": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppGrainResponse"
}
},
"has_more": {
"type": "boolean",
"description": "Whether more results are available beyond this page."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Cursor for fetching the next page (null when no more results)."
},
"offset": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
}
},
"AppRememberRequest": {
"type": "object",
"description": "Request body for POST /api/memories/{memory_id}/remember.",
"required": [
"text"
],
"properties": {
"auto_relate": {
"type": [
"boolean",
"null"
],
"description": "Auto-detect updates/extends relationships with existing grains."
},
"confidence": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Confidence for LLM-extracted facts (default 0.9)."
},
"created_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Explicit timestamp in milliseconds since epoch."
},
"extract_event_date": {
"type": [
"boolean",
"null"
],
"description": "Extract temporal references from content and auto-populate valid_from."
},
"extract_mode": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ExtractMode",
"description": "Extraction mode (issue #538 R4). `\"async\"` (default) writes an\nObservation grain immediately; `\"sync\"` runs LLM extraction\ninline. Takes precedence over the legacy `sync` field when both\nare supplied."
}
]
},
"keep_source": {
"type": "boolean",
"description": "Keep the source Observation after extraction (default: false = forget source)."
},
"namespace": {
"type": [
"string",
"null"
],
"description": "Namespace for the observation and extracted facts."
},
"source_type": {
"type": [
"string",
"null"
],
"description": "Source attribution (e.g., \"conversation\", \"note\", \"document\")."
},
"sync": {
"type": "boolean",
"description": "**Deprecated.** Legacy boolean form of `extract_mode`. Defaults to\n`false` (async). Retained for backward compatibility with clients\npinned to pre-#538 API shape; prefer `extract_mode`."
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Tags for the observation and extracted facts."
},
"text": {
"type": "string",
"description": "Natural language text to remember (1–32768 bytes)."
},
"user_id": {
"type": [
"string",
"null"
],
"description": "User ID (mandatory per compliance)."
}
}
},
"AppRememberResponse": {
"type": "object",
"description": "Response body for POST /api/memories/{memory_id}/remember.",
"required": [
"source_hash",
"mode",
"extracted_count",
"source_forgotten"
],
"properties": {
"extracted_count": {
"type": "integer",
"description": "Number of facts extracted.",
"minimum": 0
},
"extracted_hashes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hashes of facts extracted in sync mode. Empty for async."
},
"marker_status": {
"type": [
"string",
"null"
],
"description": "Extraction marker status (for async mode)."
},
"mode": {
"type": "string",
"description": "Whether sync or async extraction was used."
},
"source_forgotten": {
"type": "boolean",
"description": "Whether the source Observation was forgotten after extraction."
},
"source_hash": {
"type": "string",
"description": "Content-address hash of the source Observation grain."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warnings from the extraction pipeline."
}
}
},
"AppStatsResponse": {
"type": "object",
"description": "App stats response.",
"required": [
"total_grains",
"type_counts",
"knowledge_density",
"contradiction_rate",
"consolidation_ratio",
"retrieval_precision",
"pattern_depth",
"transfer_rate",
"correction_trend",
"growth_curve",
"decay_health",
"users",
"store_size",
"disk_space_bytes",
"type_diversity_shannon",
"avg_grain_size_bytes",
"superseded_count"
],
"properties": {
"active_agents": {
"type": [
"integer",
"null"
],
"description": "Count of agents with events in the last 24 hours.",
"minimum": 0
},
"avg_grain_size_bytes": {
"type": "integer",
"format": "int64",
"description": "Average grain size in bytes: disk_space_bytes / total_grains.",
"minimum": 0
},
"consolidation_ratio": {
"type": "number",
"format": "double"
},
"contradiction_rate": {
"type": "number",
"format": "double"
},
"correction_trend": {
"type": "number",
"format": "double"
},
"decay_health": {
"type": "number",
"format": "double"
},
"disk_space_bytes": {
"type": "integer",
"format": "int64",
"description": "Raw disk usage in bytes (machine-readable counterpart of store_size).",
"minimum": 0
},
"growth_curve": {
"type": "string"
},
"knowledge_density": {
"type": "number",
"format": "double"
},
"pattern_depth": {
"type": "number",
"format": "double"
},
"retrieval_precision": {
"type": "number",
"format": "double"
},
"store_size": {
"type": "string"
},
"superseded_count": {
"type": "integer",
"format": "int64",
"description": "Count of superseded grains.",
"minimum": 0
},
"total_grains": {
"type": "integer",
"minimum": 0
},
"transfer_rate": {
"type": "number",
"format": "double"
},
"type_counts": {
"type": "object",
"description": "Per-grain-type counts (only types with at least one grain are included).",
"additionalProperties": {
"type": "integer",
"minimum": 0
},
"propertyNames": {
"type": "string"
}
},
"type_diversity_shannon": {
"type": "number",
"format": "double",
"description": "Shannon entropy of grain type distribution: -sum(p_i * ln(p_i)).\nMax possible = ln(11) ~ 2.40 when all 11 grain types are equally distributed."
},
"users": {
"type": "integer",
"minimum": 0
}
}
},
"ApproveResponse": {
"type": "object",
"description": "Response body for `POST .../proposals/{p_id}/approve`.",
"required": [
"proposal_id",
"status",
"adds",
"supersedes",
"forgets"
],
"properties": {
"adds": {
"type": "integer",
"minimum": 0
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Per-action errors. Empty on full success; populated when the\nproposal lands in `apply_failed`."
},
"forgets": {
"type": "integer",
"minimum": 0
},
"proposal_id": {
"type": "string"
},
"status": {
"type": "string"
},
"supersedes": {
"type": "integer",
"minimum": 0
}
}
},
"ArchiveMode": {
"type": "string",
"description": "Mode for KS deletion — controls grain disposition.",
"enum": [
"disconnect",
"forget",
"both"
]
},
"ArchiveResponse": {
"type": "object",
"description": "Response body for `DELETE /knowledge-sources/{ks_id}`.",
"required": [
"status",
"mode"
],
"properties": {
"mode": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"AuditAppResponse": {
"type": "object",
"description": "Audit response (App format).",
"required": [
"entries",
"count"
],
"properties": {
"chain_total": {
"type": [
"integer",
"null"
],
"description": "Unfiltered chain total (always all-time, ignores filter/pagination).",
"minimum": 0
},
"chain_verified": {
"type": [
"boolean",
"null"
],
"description": "Overall hash chain integrity."
},
"count": {
"type": "integer",
"minimum": 0
},
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuditEntryApp"
}
},
"head_hash": {
"type": [
"string",
"null"
],
"description": "Hash of the most recent entry (chain head)."
},
"latest_event_timestamp": {
"type": [
"string",
"null"
],
"description": "Timestamp (epoch ms as string) of the most recent entry."
},
"latest_event_type": {
"type": [
"string",
"null"
],
"description": "Event type of the most recent entry."
},
"today": {
"type": [
"integer",
"null"
],
"description": "Count of events since UTC midnight today.",
"minimum": 0
},
"total": {
"type": [
"integer",
"null"
],
"description": "Total audit entries matching the current filter (for pagination).",
"minimum": 0
}
}
},
"AuditEntryApp": {
"type": "object",
"description": "Audit entry (App format).",
"properties": {
"action": {
"type": [
"string",
"null"
],
"description": "Legacy action field (kept for backward compatibility)."
},
"agent": {
"type": [
"string",
"null"
],
"description": "Who performed the action."
},
"chain_valid": {
"type": [
"boolean",
"null"
],
"description": "Whether this entry's hash chain is verified."
},
"details": {
"type": [
"string",
"null"
],
"description": "Raw technical details from the audit entry."
},
"event_type": {
"type": [
"string",
"null"
],
"description": "Event type (e.g. \"grain_created\", \"crypto_erase\")."
},
"hash": {
"type": [
"string",
"null"
],
"description": "Audit entry hash."
},
"human_description": {
"type": [
"string",
"null"
],
"description": "Human-readable description (derived at response time, not stored)."
},
"memory_id": {
"type": [
"string",
"null"
],
"description": "Memory ID this audit entry belongs to (the routing slug). Always\nthe URL `:memory_id` for the request — included so clients can\ncorrelate entries across memory listings without re-parsing the URL."
},
"memory_name": {
"type": [
"string",
"null"
],
"description": "Human-readable memory name resolved from `MemoryRegistry` at response\ntime (ADR-006 Q4 — both id and name are surfaced in the audit log).\n`None` if the memory has been deleted between event emission and\naudit read."
},
"prev_hash": {
"type": [
"string",
"null"
],
"description": "Hash of the previous audit entry (chain linkage)."
},
"sequence": {
"type": [
"integer",
"null"
],
"description": "Monotonic sequence number.",
"minimum": 0
},
"timestamp": {
"type": [
"string",
"null"
],
"description": "ISO timestamp."
}
}
},
"AuditQuery": {
"type": "object",
"description": "Audit query params.",
"properties": {
"event_type": {
"type": [
"string",
"null"
],
"description": "Filter by event type (e.g. \"grain_created\", \"crypto_erase\")."
},
"from": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Start of time range (epoch milliseconds, inclusive)."
},
"grain_hash": {
"type": [
"string",
"null"
],
"description": "Filter audit entries for a specific grain hash."
},
"limit": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"offset": {
"type": [
"integer",
"null"
],
"description": "Number of entries to skip before returning results.",
"minimum": 0
},
"query": {
"type": [
"string",
"null"
],
"description": "Search text in audit details."
},
"to": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "End of time range (epoch milliseconds, inclusive)."
},
"user_id": {
"type": [
"string",
"null"
]
}
}
},
"AuthType": {
"type": "string",
"description": "Authentication method for a provider.",
"enum": [
"api_key",
"none",
"iam"
]
},
"AuthzCheckAppResponse": {
"type": "object",
"description": "Authz check response (App format).",
"required": [
"allowed"
],
"properties": {
"allowed": {
"type": "boolean",
"description": "Whether the requested action is allowed."
},
"reason": {
"type": [
"string",
"null"
],
"description": "Human-readable explanation of the authorization decision (e.g. \"granted via tuple\" or \"no matching tuple found\")."
}
}
},
"AuthzCheckQuery": {
"type": "object",
"description": "Authz check query params.",
"properties": {
"permission": {
"type": [
"string",
"null"
]
},
"principal": {
"type": [
"string",
"null"
]
},
"resource_id": {
"type": [
"string",
"null"
]
},
"resource_type": {
"type": [
"string",
"null"
]
}
}
},
"AuthzCheckResponse": {
"type": "object",
"description": "Authorization check response.",
"required": [
"allowed"
],
"properties": {
"allowed": {
"type": "boolean"
}
}
},
"AuthzGrantRequest": {
"type": "object",
"description": "Request body for POST /memories/{memory_id}/authz/grant (D04).",
"required": [
"subject",
"relation",
"object"
],
"properties": {
"object": {
"type": "string"
},
"pseudonymized": {
"type": "boolean",
"description": "When `true`, the `subject` is already a pseudonymized token — skip HMAC.\nUsed when operating on tuples returned by `?resolve=true` that could not\nbe mapped back to a known principal."
},
"relation": {
"type": "string"
},
"subject": {
"type": "string",
"description": "Plaintext subject (e.g. \"user:john\" or \"service:atmatic-prod\").\nPseudonymized before storage and before Raft replication."
}
}
},
"AuthzGrantResponse": {
"type": "object",
"description": "Response body for POST /memories/{memory_id}/authz/grant (D04).",
"required": [
"granted",
"subject",
"relation",
"object",
"replicated"
],
"properties": {
"granted": {
"type": "boolean"
},
"object": {
"type": "string"
},
"relation": {
"type": "string"
},
"replicated": {
"type": "boolean",
"description": "`true` when the grant was Raft-replicated (distributed mode);\n`false` in standalone mode (written directly to local Fjall)."
},
"subject": {
"type": "string"
}
}
},
"AuthzListResponse": {
"type": "object",
"description": "Authorization tuple list response.",
"required": [
"count",
"tuples"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"tuples": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthzTupleResponse"
}
}
}
},
"AuthzRequest": {
"type": "object",
"description": "Authorization tuple request body.",
"required": [
"subject",
"relation",
"object"
],
"properties": {
"object": {
"type": "string"
},
"relation": {
"type": "string"
},
"subject": {
"type": "string"
}
}
},
"AuthzRevokeResponse": {
"type": "object",
"description": "Response body for POST /memories/{memory_id}/authz/revoke (D04).",
"required": [
"revoked",
"subject",
"relation",
"object",
"replicated"
],
"properties": {
"object": {
"type": "string"
},
"relation": {
"type": "string"
},
"replicated": {
"type": "boolean",
"description": "`true` when the revocation was Raft-replicated (distributed mode);\n`false` in standalone mode."
},
"revoked": {
"type": "boolean"
},
"subject": {
"type": "string"
}
}
},
"AuthzTupleResponse": {
"type": "object",
"description": "A single authorization tuple in JSON form.",
"required": [
"subject",
"relation",
"object"
],
"properties": {
"object": {
"type": "string"
},
"relation": {
"type": "string"
},
"subject": {
"type": "string"
}
}
},
"BatchAddError": {
"type": "object",
"description": "An error encountered while adding a grain in a batch-add request.",
"required": [
"index",
"error"
],
"properties": {
"error": {
"type": "string"
},
"grain_type": {
"type": [
"string",
"null"
],
"description": "The grain type that was being added (for diagnostic clarity)."
},
"index": {
"type": "integer",
"minimum": 0
},
"provided_fields": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Fields that were actually provided in the request."
},
"required_fields": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Required fields for this grain type (helps callers fix their payloads)."
}
}
},
"BatchAddRequest": {
"type": "object",
"description": "Request body for POST /api/memories/:id/batch-add -- create multiple grains of mixed types.",
"required": [
"grains"
],
"properties": {
"grains": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchGrainEntry"
},
"description": "Array of grain entries to add."
},
"namespace": {
"type": [
"string",
"null"
],
"description": "Default namespace applied to all grains that don't specify their own."
},
"source_filename": {
"type": [
"string",
"null"
],
"description": "Original filename (informational, stored in grain metadata)."
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Tags applied to ALL grains in the batch. Tags are stored on each grain and are searchable."
}
}
},
"BatchAddResponse": {
"type": "object",
"description": "Response for POST /api/memories/:id/batch-add.",
"required": [
"added",
"errors",
"total_added",
"total_errors"
],
"properties": {
"added": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchAddedGrain"
}
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchAddError"
}
},
"total_added": {
"type": "integer",
"minimum": 0
},
"total_duplicates": {
"type": "integer",
"description": "Number of grains that already existed (hash-level dedup).",
"minimum": 0
},
"total_errors": {
"type": "integer",
"minimum": 0
}
}
},
"BatchAddedGrain": {
"type": "object",
"description": "A successfully added grain in a batch-add response.",
"required": [
"index",
"blob_hash",
"grain_type"
],
"properties": {
"blob_hash": {
"type": "string"
},
"grain_type": {
"type": "string"
},
"index": {
"type": "integer",
"minimum": 0
}
}
},
"BatchGrainEntry": {
"type": "object",
"description": "A single grain entry in a batch-add request.\n\nThe `fields` object varies by `grain_type`:\n- **fact**: `subject`, `relation`, `object` (required); `confidence`, `source_agent`, `namespace`, `tags` (optional)\n- **event**: `content` (required); `subject`, `namespace`, `tags` (optional)\n- **state**: `data` (optional, defaults to `{}`); `subject`, `session_id`, `namespace` (optional)\n- **action**: `tool_name` (required); `input`, `content`, `is_error`, `duration_ms`, `subject`, `task_id`, `session_id` (optional)\n- **observation**: `content` (required); `observer_id` (optional, defaults to \"unknown\"), `observer_type` (optional, defaults to \"agent\"), `subject`, `object`, `namespace` (optional)\n- **goal**: `description` (required, or `object` as fallback); `subject`, `parent_goal`, `session_id` (optional)\n- **reasoning**: (no required fields); `conclusion`, `inference_method`, `subject`, `namespace` (optional)\n- **consensus**: (no required fields); `participating_observers`, `threshold`, `agreement_count`, `dissent_count`, `dissent_grains`, `agreed_content` (optional)\n- **consent**: `subject_did` AND `user_id` (both required); `purpose`, `granted`, `scope`, `expiry` (optional). Omitting either required field returns 422.",
"required": [
"grain_type",
"fields"
],
"properties": {
"fields": {
"type": "object",
"description": "Fields specific to the grain type. See struct-level documentation for per-type requirements."
},
"grain_type": {
"type": "string",
"description": "Grain type: fact, event, state, workflow, tool, observation, goal, reasoning, consensus, consent, or skill."
}
}
},
"BindToolRequest": {
"type": "object",
"description": "Request body for POST /harnesses/{slug}/bind-tool.",
"required": [
"executor",
"param_schema",
"output_schema"
],
"properties": {
"annotations": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ToolAnnotations",
"description": "MCP-style side-effect annotations. `read_only && destructive` is\nrejected with `MEM-E103` at bind time."
}
]
},
"async_mode": {
"type": [
"boolean",
"null"
]
},
"cross_region_ack": {
"type": "boolean",
"description": "HPL design C9 — caller explicitly acknowledges that a\n`client://` binding on a memory with `data_residency` set may\nexport payloads outside the residency zone. Required when both\nconditions hold; ignored otherwise. Audit entry\n`CrossBorderTransferExecuted` is emitted at bind time."
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {}
},
"executor": {
"$ref": "#/components/schemas/ExecutorSpec",
"description": "Executor that will run this tool — see [`ExecutorSpec`]. The\ncanonical `tool_id` (`connector.action` for axtion, the\n`executor_id` for client) is derived from this; callers do not\nconstruct identifier strings themselves."
},
"locked_params": {
"type": "object",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
},
"output_schema": {},
"param_schema": {},
"spec_hash": {
"type": [
"string",
"null"
]
}
}
},
"BindToolResponse": {
"type": "object",
"required": [
"tool_hash",
"tool_id",
"namespace"
],
"properties": {
"namespace": {
"type": "string"
},
"tool_hash": {
"type": "string"
},
"tool_id": {
"type": "string"
}
}
},
"BoundToolEntry": {
"type": "object",
"required": [
"tool_hash",
"tool_id",
"description",
"axtion_uri",
"created_at_ms",
"baa_ok",
"executor_kind"
],
"properties": {
"axtion_uri": {
"type": "string"
},
"baa_ok": {
"type": "boolean",
"description": "Whether this tool is BAA-blocked under the current memory's\nHIPAA posture. When the memory has no HIPAA policy active, this\nis always `true`."
},
"connection_auth_type": {
"type": [
"string",
"null"
],
"description": "Auth type of the active connection (e.g., \"oauth\", \"api_key\")."
},
"connection_id": {
"type": [
"string",
"null"
],
"description": "ID of the active ConnectionRecord, for disconnect operations."
},
"connection_status": {
"type": [
"string",
"null"
],
"description": "Connection status for this tool's connector in the current memory.\n`\"connected\"` or `\"not_connected\"`; `None` for built-in tools."
},
"connector_name": {
"type": [
"string",
"null"
],
"description": "Connector name extracted from tool_id prefix (e.g., \"slack\" from\n\"slack.post_message\"). `None` for built-in tools without a dot."
},
"created_at_ms": {
"type": "integer",
"format": "int64"
},
"description": {
"type": "string"
},
"executor_kind": {
"type": "string",
"description": "HPL Phase 4.1 — runtime executor for this binding. Sourced from\nthe persisted Tool grain's `executor_kind` field, defaulting to\n`\"axtion\"` for pre-HPL bindings (no migration). Frontends should\nbranch on this rather than parsing `axtion_uri` prefixes."
},
"spec_hash": {
"type": [
"string",
"null"
]
},
"tool_hash": {
"type": "string"
},
"tool_id": {
"type": "string"
}
}
},
"BoundToolsResponse": {
"type": "object",
"required": [
"harness_slug",
"namespace",
"hipaa_active",
"tools"
],
"properties": {
"harness_slug": {
"type": "string"
},
"hipaa_active": {
"type": "boolean"
},
"namespace": {
"type": "string"
},
"tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BoundToolEntry"
}
}
}
},
"BreachDeadlineView": {
"type": "object",
"description": "One open breach deadline row for `GET /memories/{id}/compliance/breach-deadlines`\n(issue #572).",
"required": [
"breach_id",
"deadline_at_ms",
"statutory_deadline_at_ms",
"affected_individuals_estimate",
"severity_score",
"reported_at_ms",
"resolved",
"overdue"
],
"properties": {
"affected_individuals_estimate": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"breach_id": {
"type": "string"
},
"deadline_at_ms": {
"type": "integer",
"format": "int64"
},
"overdue": {
"type": "boolean",
"description": "`true` when the internal 48h window has already closed (PDP-E002 risk)."
},
"reported_at_ms": {
"type": "integer",
"format": "int64"
},
"resolved": {
"type": "boolean"
},
"severity_score": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"statutory_deadline_at_ms": {
"type": "integer",
"format": "int64"
}
}
},
"BreachReportRequest": {
"type": "object",
"description": "`POST /memories/{id}/compliance/breach` request (issue #572). Admin-scoped.",
"required": [
"affected_individuals"
],
"properties": {
"affected_individuals": {
"type": "integer",
"format": "int64",
"description": "Estimated number of affected data subjects.",
"minimum": 0
},
"breach_id": {
"type": [
"string",
"null"
],
"description": "Optional caller breach id; a UUID is generated when omitted."
},
"severity_score": {
"type": "integer",
"format": "int32",
"description": "Harm severity score (0–100). ≥50 is notifiable on the significant-harm limb.",
"minimum": 0
},
"triggering_event_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Triggering-event time (UTC epoch ms). Defaults to server-now."
}
}
},
"BreachReportResponse": {
"type": "object",
"description": "Response for the breach-report endpoint (issue #572).",
"required": [
"notifiable"
],
"properties": {
"breach_id": {
"type": [
"string",
"null"
],
"description": "The breach id (echoed/generated) when notifiable."
},
"deadline_at_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Internal 48h deadline (UTC epoch ms) when notifiable."
},
"notifiable": {
"type": "boolean",
"description": "Whether the breach met the PDPC notifiable threshold (recorded only if true)."
},
"statutory_deadline_at_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Statutory 72h PDPC deadline (UTC epoch ms) when notifiable."
}
}
},
"BrowseItem": {
"type": "object",
"description": "One item in a browse response (file or folder).",
"required": [
"id",
"name",
"mime_type",
"is_folder"
],
"properties": {
"id": {
"type": "string"
},
"is_folder": {
"type": "boolean"
},
"mime_type": {
"type": "string"
},
"modified_time": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"size": {
"type": [
"integer",
"null"
],
"format": "int64",
"minimum": 0
}
}
},
"BrowseResponse": {
"type": "object",
"description": "Response body for `POST /knowledge-sources/{ks_id}/browse`.\n\nMirrors atmatic-studio's `BrowseResult` contract — uniform across connectors.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowseItem"
},
"description": "Items returned by the connector. Each is a folder or a file."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page; `None` when there are no more results."
}
}
},
"BulkPullStatsRequest": {
"type": "object",
"required": [
"hashes"
],
"properties": {
"hashes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to 256 grain hashes (hex-encoded SHA-256) to look up in a single call."
}
}
},
"BulkPullStatsResponse": {
"type": "object",
"description": "OpenAPI-only schema for the bulk pull-stats response body.",
"required": [
"stats"
],
"properties": {
"stats": {
"type": "object",
"description": "Map of grain hash (hex) → pull-stats record. Hashes the caller cannot\nread (or that reference unknown grains) are silently omitted.",
"additionalProperties": {
"$ref": "#/components/schemas/PullStatsRecord"
},
"propertyNames": {
"type": "string"
}
}
}
},
"CallbackAck": {
"type": "object",
"required": [
"accepted",
"deduped",
"rejected"
],
"properties": {
"accepted": {
"type": "integer",
"minimum": 0
},
"deduped": {
"type": "integer",
"minimum": 0
},
"rejected": {
"type": "integer",
"minimum": 0
},
"resolved_grain_hash": {
"type": [
"string",
"null"
]
}
}
},
"CatalogProviderSummary": {
"type": "object",
"description": "Summary of a catalog provider for the list endpoint.",
"required": [
"id",
"display_name",
"provider_type",
"auth_type",
"auth_env_hint",
"api_key_set",
"base_url",
"enabled",
"status"
],
"properties": {
"api_key_set": {
"type": "boolean",
"description": "True if an API key has been stored; the value is never returned."
},
"auth_env_hint": {
"type": "string"
},
"auth_type": {
"$ref": "#/components/schemas/AuthType"
},
"base_url": {
"type": "string"
},
"base_url_override": {
"type": [
"string",
"null"
]
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string"
},
"provider_type": {
"$ref": "#/components/schemas/ProviderType"
},
"status": {
"$ref": "#/components/schemas/ProviderStatus"
}
}
},
"CensusSessionStat": {
"type": "object",
"description": "Per-session statistics for session-census retrieval.",
"required": [
"namespace",
"grains_found",
"grains_merged",
"top_score"
],
"properties": {
"grains_found": {
"type": "integer",
"description": "Number of grains returned by the follow-up query (before dedup).",
"minimum": 0
},
"grains_merged": {
"type": "integer",
"description": "Number of grains that passed min_score and dedup to be merged.",
"minimum": 0
},
"namespace": {
"type": "string",
"description": "The namespace (session) that was queried."
},
"top_score": {
"type": "number",
"format": "double",
"description": "Top score among the merged grains (for observability)."
}
}
},
"ChangeProposal": {
"type": "object",
"description": "One persisted change proposal — the full record stored under\n`change_proposals`. Carries every grain mutation the apply step will\nrun when the user (or auto-sync) approves.",
"required": [
"proposal_id",
"memory_id",
"ks_id",
"source_file_id",
"status",
"generated_at_ms",
"change_id",
"grain_actions"
],
"properties": {
"change_id": {
"type": "string",
"description": "Idempotency key from the Axtion callback that produced this proposal.\nDuplicates of the same `change_id` are rejected at intake (see\nrequirements §10.3 idempotency-keys table)."
},
"decided_at_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Wall-clock time the proposal entered `applied | rejected | expired\n| superseded | apply_failed`."
},
"decided_by": {
"type": [
"string",
"null"
],
"description": "Optional user that approved/rejected — `None` while `pending`.\nSet by `set_change_proposal` when transitioning to a terminal state."
},
"generated_at_ms": {
"type": "integer",
"format": "int64",
"description": "Wall-clock time the proposal was generated."
},
"grain_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GrainAction"
},
"description": "Concrete grain mutations the applier will run if approved. Order\nmatters: `Add` actions run before `Supersede` so that a crash\nbetween the two leaves the new content reachable, not the supersede\ndangling. See requirements §10.3 sharp rule."
},
"ks_id": {
"type": "string"
},
"memory_id": {
"type": "string"
},
"proposal_id": {
"type": "string",
"description": "ULID — primary key within `(memory_id, ks_id)`."
},
"source_file_id": {
"type": "string",
"description": "Source file the proposal is scoped to. One file = one proposal.\nMulti-file changes turn into N proposals; the alerts aggregator\ncollapses them per-KS for the user."
},
"status": {
"$ref": "#/components/schemas/ProposalStatus"
}
}
},
"ChatRequest": {
"type": "object",
"description": "POST /api/memories/{id}/chat request body.",
"required": [
"messages"
],
"properties": {
"attachment_imports": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Unique import job ids for the files attached this turn (parallel to\n`attachments`). Imported grains are tagged `import:{id}`, so the chat\nengine scopes recall to these ids — unambiguous even when two files\nshare a name. Falls back to the `source:{filename}` tag when absent."
},
"attachments": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Filenames attached to this turn (file-import flow). Persisted on the\nlast user message so the UI re-renders the attachment card on reload,\nand surfaced to the LLM via the system prompt. Never forwarded verbatim\nto the LLM provider."
},
"context_limit": {
"type": [
"integer",
"null"
],
"description": "Max auto-recall results for context (default: 10, max: 100).",
"minimum": 0
},
"conversation_id": {
"type": [
"string",
"null"
],
"description": "Conversation ID for multi-turn context."
},
"messages": {
"type": "array",
"items": {
"type": "object"
},
"description": "OpenAI-compatible chat messages (role + content)."
},
"model": {
"type": [
"string",
"null"
],
"description": "Optional model override (falls back to stored settings)."
},
"provider": {
"type": [
"string",
"null"
],
"description": "Optional provider override (falls back to stored settings)."
},
"thread_id": {
"type": [
"string",
"null"
],
"description": "Thread ID for persistent conversation history.\nWhen present, messages are loaded from and saved to the thread store\ninstead of the ephemeral ConversationStore."
},
"tools_enabled": {
"type": "boolean",
"description": "Enable tool calling (default: true)."
},
"user_action": {
"type": [
"object",
"null"
],
"description": "A2UI user action (bypasses LLM — direct execution)."
}
}
},
"ChatResumeRequest": {
"type": "object",
"required": [
"session_id",
"tool_outputs"
],
"properties": {
"session_id": {
"type": "string"
},
"tenant_timestamp_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Forensic only — caller's claimed tool-exec wallclock (ms). Any\nvalue is accepted and persisted alongside the server-side\nwallclock (SR P-3)."
},
"tool_outputs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatToolOutput"
}
}
}
},
"ChatStreamRequest": {
"type": "object",
"description": "Request body for POST /api/memories/:id/chat/stream.",
"required": [
"messages"
],
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object"
},
"description": "OpenAI-compatible chat messages array."
},
"model": {
"type": [
"string",
"null"
],
"description": "Optional model override (uses stored settings if absent)."
},
"provider": {
"type": [
"string",
"null"
],
"description": "Optional provider override (uses stored settings if absent)."
}
}
},
"ChatToolDispatchRequest": {
"type": "object",
"description": "Body for `POST /api/memories/:id/chat/tools/:tool` —\neither `context` (a2ui Button context, flat string map) or\n`params` (LLM-style JSON object). Front-end senders use\n`context`; ad-hoc API callers can use either.",
"properties": {
"context": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
},
"propertyNames": {
"type": "string"
}
},
"params": {}
}
},
"ChatToolDispatchResponse": {
"type": "object",
"description": "Wire shape returned by the dispatch endpoint. Mirrors the chat-tool\n`ToolResult` minus the pipeline-stages field (deterministic-button\ntools are not pipeline-shaped) and with the a2ui surface unrolled\ninto a JSON message array the Angular `parseSurfaces` helper consumes.",
"required": [
"text"
],
"properties": {
"a2ui_messages": {
"type": "array",
"items": {}
},
"preview_data": {},
"text": {
"type": "string"
}
}
},
"ChatToolOutput": {
"type": "object",
"required": [
"tool_call_id",
"output"
],
"properties": {
"is_error": {
"type": "boolean"
},
"output": {
"description": "Structured tool output, instance-validated against the binding's\n`output_schema`. Accepted shapes: object, array, scalar — the\nstored schema drives what's allowed."
},
"tool_call_id": {
"type": "string"
}
}
},
"CompileContextQuery": {
"type": "object",
"description": "Query params for compile_context.",
"properties": {
"token_budget": {
"type": [
"integer",
"null"
],
"description": "Token budget (default: 4096).",
"minimum": 0
}
}
},
"ComplianceGroupMetric": {
"type": "object",
"description": "Per-group compliance metric.",
"required": [
"group",
"label",
"total",
"passed"
],
"properties": {
"group": {
"type": "string"
},
"label": {
"type": "string"
},
"passed": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
}
},
"ComplianceImpactResponse": {
"type": "object",
"description": "Compliance impact response — full impact assessment report.\n\nWhen format=json (default), returns the complete ImpactAssessment with\nmetadata, system_description, data_practices, usage_analysis,\ndisparity_analysis, risk_assessment, and mitigations.\nWhen format=text/nist/colorado/iso42001, returns `{text: string}`.",
"properties": {
"data_practices": {
"description": "Data practices (collection methods, retention, PII/PHI detection, erasure, consent)."
},
"disparity_analysis": {
"description": "Disparity analysis (demographic disparity detection results)."
},
"metadata": {
"description": "Report metadata (generated_at, areev_version, assessment_type, regulatory_basis)."
},
"mitigations": {
"description": "Mitigation measures."
},
"risk_assessment": {
"description": "Risk assessment (overall risk level, compliance check results)."
},
"system_description": {
"description": "System description (system_name, purpose, grain types, totals, encryption/audit status)."
},
"text": {
"type": [
"string",
"null"
],
"description": "Formatted text output (present when format=text/nist/colorado/iso42001)."
},
"usage_analysis": {
"description": "Usage analysis (per-namespace stats, grain type distribution)."
}
}
},
"ComplianceMetricsResponse": {
"type": "object",
"description": "Compliance metrics summary.",
"required": [
"memory_id",
"has_encryption",
"has_audit",
"has_agent_identity",
"total_checks",
"passed",
"failed",
"groups",
"severity_counts"
],
"properties": {
"failed": {
"type": "integer",
"minimum": 0
},
"groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ComplianceGroupMetric"
}
},
"has_agent_identity": {
"type": "boolean"
},
"has_audit": {
"type": "boolean"
},
"has_encryption": {
"type": "boolean"
},
"memory_id": {
"type": "string"
},
"monitor": {
"description": "Real-time compliance monitor metrics (present only if monitor is attached)."
},
"passed": {
"type": "integer",
"minimum": 0
},
"severity_counts": {
"$ref": "#/components/schemas/ComplianceSeverityCounts",
"description": "Severity breakdown across all checks (critical, warning, info counts)."
},
"total_checks": {
"type": "integer",
"minimum": 0
}
}
},
"ComplianceSeverityCounts": {
"type": "object",
"description": "Severity breakdown counts for compliance checks.",
"required": [
"critical",
"warning",
"info"
],
"properties": {
"critical": {
"type": "integer",
"minimum": 0
},
"info": {
"type": "integer",
"minimum": 0
},
"warning": {
"type": "integer",
"minimum": 0
}
}
},
"ComplianceVerification": {
"type": "object",
"description": "Compliance verification freshness metadata for the alerts response.",
"required": [
"status"
],
"properties": {
"duration_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "How long the last verification took, in milliseconds.",
"minimum": 0
},
"last_verified_at": {
"type": [
"string",
"null"
],
"description": "When the included compliance data was computed (ISO 8601).\n`None` only when `status` is `\"pending\"` (never verified yet)."
},
"status": {
"type": "string",
"description": "`\"verified\"` — fresh cached results included in this response.\n`\"pending\"` — first verification is running in the background;\n a placeholder alert is shown (not a real finding).\n`\"stale\"` — previous results included but older than TTL;\n a background refresh has been triggered."
}
}
},
"ComplianceViolation": {
"type": "object",
"description": "A single compliance violation.",
"required": [
"check_id",
"group",
"description",
"detail",
"severity",
"regulation",
"article"
],
"properties": {
"article": {
"type": "string"
},
"check_id": {
"type": "string"
},
"description": {
"type": "string"
},
"detail": {
"type": "string"
},
"first_detected_at": {
"type": [
"string",
"null"
]
},
"group": {
"type": "string"
},
"regulation": {
"type": "string"
},
"severity": {
"type": "string",
"description": "Severity: \"Critical\", \"Warning\", or \"Info\"."
}
}
},
"ComplianceViolationsResponse": {
"type": "object",
"description": "List of compliance violations.",
"required": [
"violations",
"total_checks",
"passed",
"failed",
"regulation_counts"
],
"properties": {
"failed": {
"type": "integer",
"minimum": 0
},
"monitor_violations": {
"description": "Real-time monitor violations (present only if monitor is attached)."
},
"passed": {
"type": "integer",
"minimum": 0
},
"regulation_counts": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
},
"propertyNames": {
"type": "string"
}
},
"total_checks": {
"type": "integer",
"minimum": 0
},
"violations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ComplianceViolation"
}
}
}
},
"ConnectionTestResponse": {
"type": "object",
"description": "POST /api/settings/providers/{provider_id}/test response.",
"required": [
"status"
],
"properties": {
"latency_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"minimum": 0
},
"message": {
"type": [
"string",
"null"
]
},
"provider_version": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
}
}
},
"ConnectorMeta": {
"oneOf": [
{
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"none"
]
}
}
},
{
"type": "object",
"required": [
"cloud_id",
"kind"
],
"properties": {
"cloud_id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"confluence"
]
}
}
},
{
"type": "object",
"required": [
"workspace_name",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"notion"
]
},
"workspace_name": {
"type": "string"
}
}
}
],
"description": "Connector-tenant identifier (e.g. Atlassian Cloud ID). Populated by the\nconnector at create time; opaque to the orchestrator."
},
"ConsentBulkGrantRequest": {
"type": "object",
"description": "Request to grant consent in bulk.",
"required": [
"user_ids"
],
"properties": {
"purpose": {
"type": "string"
},
"user_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ConsentCheckResponse": {
"type": "object",
"description": "Per-`(user_id, purpose, disclosure_version)` consent check response.\n\nReturned by `GET /memories/{id}/consent/check`. The `granted` field is\n`true` only when a record exists AND its `disclosure_version` matches\nthe value supplied in the query — older grants under prior versions\nsurface as `granted: false` with the recorded version still visible\n(so the client can render \"you previously consented to v0; here is v1\").",
"required": [
"granted",
"scope",
"purpose",
"user_id"
],
"properties": {
"disclosure_version": {
"type": [
"string",
"null"
]
},
"granted": {
"type": "boolean"
},
"granted_at": {
"type": [
"string",
"null"
]
},
"purpose": {
"type": "string"
},
"scope": {
"type": "array",
"items": {
"type": "string"
}
},
"user_id": {
"type": "string"
}
}
},
"ConsentGrantRequest": {
"type": "object",
"description": "Request to grant consent for a user.\n\nBackwards compatible: legacy admin callers send `{user_id, purpose}` only.\nThe user-driven SSOT path additionally sends `disclosure_version` + `scope`\nto satisfy GDPR Art. 7(1) demonstrability. Omitted optional fields default\nto `None` / `vec![]` — preserving wire-format compat with existing callers.",
"required": [
"user_id"
],
"properties": {
"disclosure_version": {
"type": [
"string",
"null"
]
},
"purpose": {
"type": "string"
},
"scope": {
"type": "array",
"items": {
"type": "string"
}
},
"user_id": {
"type": "string"
}
}
},
"ConsentRequest": {
"type": "object",
"description": "Request body for consent operations.",
"required": [
"user_id",
"purpose"
],
"properties": {
"purpose": {
"type": "string"
},
"user_id": {
"type": "string"
}
}
},
"ConsentStatusResponse": {
"type": "object",
"description": "Consent status response.\n\nBy default, `without_consent_list` is omitted for privacy (SEC-PROBE-04).\nPass `?include_ids=true` to include the plaintext user ID list.",
"required": [
"consent_level",
"total_users",
"users_with_consent",
"users_without_consent"
],
"properties": {
"consent_level": {
"type": "string"
},
"total_users": {
"type": "integer",
"minimum": 0
},
"users_with_consent": {
"type": "integer",
"minimum": 0
},
"users_without_consent": {
"type": "integer",
"minimum": 0
},
"without_consent_list": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
}
}
},
"ConsolidateRequest": {
"type": "object",
"description": "Request body for consolidation.",
"properties": {
"threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Similarity threshold (0.0-1.0, default 0.85)."
}
}
},
"CreateGoalRequest": {
"type": "object",
"description": "Request body for creating a goal.",
"required": [
"description"
],
"properties": {
"criteria": {
"type": [
"string",
"null"
]
},
"description": {
"type": "string"
},
"parent_goal_hash": {
"type": [
"string",
"null"
]
},
"priority": {
"type": [
"string",
"null"
]
}
}
},
"CreateHookRequest": {
"type": "object",
"description": "Request body for creating a hook.",
"required": [
"name"
],
"properties": {
"acknowledge_pii_risk": {
"type": "boolean",
"description": "Acknowledge PII risk override for redaction mode (COMP-H1)."
},
"delivery_mode": {
"type": "string",
"description": "Delivery mode: \"cdc\" (default) or \"webhook\"."
},
"event_filters": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event type filters (empty = all types)."
},
"generate_secret": {
"type": "boolean",
"description": "Generate HMAC signing secret (webhook mode only)."
},
"name": {
"type": "string"
},
"redaction_mode": {
"type": "string",
"description": "Redaction mode: \"full\" (default), \"metadata_only\", or \"hash_only\"."
},
"url": {
"type": [
"string",
"null"
],
"description": "Webhook URL (required for webhook mode)."
}
}
},
"CreateKsRequest": {
"type": "object",
"description": "Request body for `POST /knowledge-sources` (create draft).\n\n`web_search` connector ignores `connection_id` (cell synthesises a\n`system:web_search` sentinel) and ignores `scope.files[]` (the\ncanonical input is the top-level `url`). All other connectors use\n`connection_id` + `scope.files[]` as before.",
"required": [
"name",
"connector_name"
],
"properties": {
"connection_id": {
"type": "string"
},
"connector_display_name": {
"type": "string"
},
"connector_name": {
"type": "string"
},
"main_content_only": {
"type": [
"boolean",
"null"
],
"description": "`web_search` only — currently always treated as `true` upstream\n(data-minimisation default per WS-1.0 disclosure). Reserved for\nv2 wizard exposure."
},
"name": {
"type": "string"
},
"scope": {
"$ref": "#/components/schemas/KsScope"
},
"sync_policy": {
"$ref": "#/components/schemas/SyncPolicy"
},
"url": {
"type": [
"string",
"null"
],
"description": "`web_search` only — canonical URL to fetch. Required when\n`connector_name == \"web_search\"`; ignored otherwise."
}
}
},
"CreateMemoryRequest": {
"type": "object",
"description": "Create memory request body.",
"required": [
"name"
],
"properties": {
"dedup": {
"type": [
"string",
"null"
],
"description": "Write-path dedup policy: \"none\" (default), \"exact\", \"fuzzy\", \"upsert\"."
},
"dedup_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Fuzzy dedup similarity threshold (0.0-1.0, default 0.85)."
},
"description": {
"type": [
"string",
"null"
]
},
"guardrail_mode": {
"type": [
"string",
"null"
],
"description": "Guardrail match mode: \"exact\", \"contains\" (default), or \"fuzzy\"."
},
"guardrail_patterns": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Guardrail patterns: list of text patterns that block content from being stored."
},
"guardrail_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Fuzzy guardrail threshold (0.0-1.0, default 0.8)."
},
"memory_id": {
"type": [
"string",
"null"
],
"description": "**Pilot-internal field.** When set, the cell uses this slug as the\n`memory_id` instead of slugifying `name` itself. Pilot owns slug\nallocation in cloud mode (ADR-006); the cell receives a pre-allocated\n`(memory_id, name)` pair via the L7 proxy, gated by the\n`X-Pilot-Internal` header. External clients should not set this — it\nis harmless on the standalone path (just bypasses the cell's own\nslugify) but is normally set only by Pilot."
},
"name": {
"type": "string"
},
"policy": {
"type": [
"string",
"null"
],
"description": "Policy preset to apply atomically at creation time.\nOne of: \"gdpr\", \"ccpa\", \"hipaa\", \"lgpd\", \"pipl\", \"sox\", \"ephemeral\", \"default\".\nIf omitted, the server-level default policy is used."
},
"vector_backend": {
"type": [
"string",
"null"
],
"description": "Vector backend: \"usearch\" (default) or \"faiss\". Only effective when the\ncorresponding feature is compiled in."
}
},
"additionalProperties": false
},
"CreateThreadRequest": {
"type": "object",
"description": "Request body for creating a thread.",
"properties": {
"title": {
"type": [
"string",
"null"
]
}
}
},
"CreateWorkspaceDekRequest": {
"type": "object",
"description": "Request body for `POST /api/crypto/workspace-dek`.",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "string"
}
}
},
"CreateWorkspaceDekResponse": {
"type": "object",
"description": "Response for `POST /api/crypto/workspace-dek` (201 Created).",
"required": [
"keyVersion",
"wrappedAt",
"fingerprint"
],
"properties": {
"fingerprint": {
"type": "string"
},
"keyVersion": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"wrappedAt": {
"type": "string"
}
}
},
"CustomModel": {
"type": "object",
"description": "A user-defined model on a custom provider.",
"required": [
"id",
"display_name",
"capabilities"
],
"properties": {
"capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelCapability"
}
},
"display_name": {
"type": "string"
},
"id": {
"type": "string"
}
}
},
"CustomProviderSummary": {
"type": "object",
"description": "Summary of a custom provider for the list endpoint.",
"required": [
"id",
"display_name",
"provider_type",
"base_url",
"auth_type",
"api_key_set",
"models",
"enabled",
"status"
],
"properties": {
"api_key_set": {
"type": "boolean"
},
"auth_type": {
"$ref": "#/components/schemas/AuthType"
},
"base_url": {
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string"
},
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomModel"
}
},
"provider_type": {
"$ref": "#/components/schemas/ProviderType"
},
"status": {
"$ref": "#/components/schemas/ProviderStatus"
}
}
},
"DataResidencyView": {
"type": "object",
"description": "Data-residency projection (issue #570) — surfaced in policy responses.",
"required": [
"allowed_regions",
"enforcement"
],
"properties": {
"allowed_regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Region ids data may physically reside in (e.g. `[\"sg\"]`)."
},
"enforcement": {
"type": "string",
"description": "`\"enforce\"` (hard-blocks cross-region writes with PDP-E001) or\n`\"disabled\"` (advisory)."
}
}
},
"DelegateGoalRequest": {
"type": "object",
"description": "Request body for delegating a goal.",
"required": [
"delegate_to",
"description"
],
"properties": {
"delegate_to": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"DetectPiiDetailedRequest": {
"type": "object",
"description": "Request body for detailed PII detection (Phase 2).",
"required": [
"text"
],
"properties": {
"detailed": {
"type": "boolean",
"description": "When true, return full match details; when false, return category tags only."
},
"text": {
"type": "string"
}
}
},
"DetectPiiDetailedResponse": {
"type": "object",
"description": "Detailed PII detection response with match positions and confidence scores.",
"required": [
"matches",
"count"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"matches": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PiiMatchResponse"
}
}
}
},
"DiffStatesRequest": {
"type": "object",
"description": "Request body for diffing two state grains.",
"required": [
"old_hash",
"new_hash"
],
"properties": {
"new_hash": {
"type": "string"
},
"old_hash": {
"type": "string"
}
}
},
"EnforcementControlStatus": {
"type": "object",
"description": "Status of a single policy control for enforcement.",
"required": [
"name",
"action_needed",
"action_type",
"impact"
],
"properties": {
"action_needed": {
"type": "boolean"
},
"action_type": {
"type": "string"
},
"impact": {
"type": "object"
},
"name": {
"type": "string"
}
}
},
"EnforcementStatusResponse": {
"type": "object",
"description": "Response for enforcement status check.",
"required": [
"controls"
],
"properties": {
"controls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnforcementControlStatus"
}
}
}
},
"ErasureProofResponse": {
"type": "object",
"description": "Erasure proof response.",
"required": [
"user_id",
"count",
"key_fingerprint",
"timestamp"
],
"properties": {
"count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"key_fingerprint": {
"type": "string"
},
"timestamp": {
"type": "integer",
"format": "int64"
},
"user_id": {
"type": "string"
}
}
},
"ErrorResponse": {
"type": "object",
"description": "Standard error response.",
"required": [
"error",
"code"
],
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
}
},
"EventsQuery": {
"type": "object",
"description": "Query params for event polling.",
"properties": {
"max_events": {
"type": [
"integer",
"null"
],
"description": "Max events to return (default: 100, max: 1000).",
"minimum": 0
},
"timeout_ms": {
"type": [
"integer",
"null"
],
"description": "Max time to wait for events in milliseconds (default: 5000, max: 30000).",
"minimum": 0
}
}
},
"ExecRequest": {
"type": "object",
"description": "App exec request body.",
"required": [
"code"
],
"properties": {
"code": {
"type": "string"
}
}
},
"ExecResponse": {
"type": "object",
"description": "App exec response.",
"required": [
"output"
],
"properties": {
"error": {
"type": [
"string",
"null"
]
},
"output": {
"type": "string"
}
}
},
"ExecutorSpec": {
"oneOf": [
{
"type": "object",
"required": [
"connector",
"action",
"type"
],
"properties": {
"action": {
"type": "string"
},
"connector": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"axtion"
]
}
}
},
{
"type": "object",
"required": [
"executor_id",
"type"
],
"properties": {
"executor_id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"client"
]
}
}
}
],
"description": "Structured executor specification for `bind-tool`. Identifies who\nruns the tool when the LLM emits a call, plus the routing identity\nfor that executor. Replaces the prior dual `tool_id` + `axtion_uri`\nstring fields — those two had to agree but were validated\nindependently, so a mismatch produced a runtime failure at first\ninvoke instead of a clean reject at bind time.\n\n`axtion` — the cell dispatches via gRPC to Axtion; `(connector,\naction)` is the routing tuple. `client` — the external caller\nexecutes the tool through Flow A's pause/resume contract;\n`executor_id` is the opaque token the caller supplies."
},
"ExhaustiveMetadata": {
"type": "object",
"description": "Metadata about exhaustive recall execution, returned in RecallResult.\n\nProvides observability into the expansion process: how many rounds\nran, which entities were discovered, and how many unique grains each\nround contributed. Useful for debugging, benchmarking, and provenance.",
"required": [
"rounds_executed",
"entities_found",
"initial_unique_count",
"final_unique_count",
"round_stats",
"converged"
],
"properties": {
"converged": {
"type": "boolean",
"description": "True when expansion terminated because a round added 0 new hashes\n(convergence). False when terminated by max_rounds limit."
},
"entities_found": {
"type": "array",
"items": {
"type": "string"
},
"description": "Unique entity mentions (subjects) discovered across all rounds."
},
"expansion_grains_budget_capped": {
"type": "integer",
"description": "RF-1: Number of expansion grains dropped by per-round budget cap.",
"minimum": 0
},
"expansion_grains_filtered": {
"type": "integer",
"description": "RF-1: Number of expansion grains dropped by min_score gate.",
"minimum": 0
},
"expansion_score_cap": {
"type": [
"number",
"null"
],
"format": "double",
"description": "RF-1: The score cap applied to expansion grains\n(original_top10_min - 0.05), or None if fewer than 1 initial hit."
},
"final_unique_count": {
"type": "integer",
"description": "Number of unique grain hashes after all expansion rounds.",
"minimum": 0
},
"initial_unique_count": {
"type": "integer",
"description": "Number of unique grain hashes after the initial recall pass.",
"minimum": 0
},
"round_stats": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExhaustiveRoundStat"
},
"description": "Per-round stats."
},
"rounds_executed": {
"type": "integer",
"format": "int32",
"description": "Number of expansion rounds executed (0 = only initial pass).",
"minimum": 0
}
}
},
"ExhaustiveRoundStat": {
"type": "object",
"description": "Per-round statistics for exhaustive recall.",
"required": [
"round",
"queries_issued",
"new_hashes"
],
"properties": {
"budget_capped": {
"type": "integer",
"description": "Number of grains dropped by budget cap in this round.",
"minimum": 0
},
"filtered_by_min_score": {
"type": "integer",
"description": "Number of grains filtered by min_score in this round.",
"minimum": 0
},
"new_hashes": {
"type": "integer",
"description": "Number of new unique grain hashes discovered in this round\n(not seen in any previous round).",
"minimum": 0
},
"queries_issued": {
"type": "integer",
"description": "Number of entity variants queried in this round.",
"minimum": 0
},
"round": {
"type": "integer",
"format": "int32",
"description": "1-indexed round number.",
"minimum": 0
}
}
},
"ExportFileQuery": {
"type": "object",
"description": "Export file query params.",
"properties": {
"grain_type": {
"type": [
"string",
"null"
]
},
"namespace": {
"type": [
"string",
"null"
]
}
}
},
"ExportUserResponse": {
"type": "object",
"description": "Export user data response.",
"required": [
"user_id",
"records",
"format"
],
"properties": {
"format": {
"type": "string"
},
"records": {
"type": "object"
},
"user_id": {
"type": "string"
}
}
},
"ExtraToolDef": {
"type": "object",
"description": "Per-request overlay tool definition. Shape kept flat for v1; the\nSDKs adapt provider-native shapes (OpenAI Chat Completions, etc.)\ninto this on the way over the wire.",
"required": [
"name",
"input_schema"
],
"properties": {
"description": {
"type": [
"string",
"null"
]
},
"input_schema": {},
"name": {
"type": "string"
}
}
},
"ExtractDocumentResponse": {
"type": "object",
"description": "Response for POST /api/memories/:id/extract-document -- text extraction only, no grain creation.",
"required": [
"filename",
"format",
"total_chunks",
"chunks"
],
"properties": {
"chunks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExtractedChunk"
}
},
"filename": {
"type": "string"
},
"format": {
"type": "string"
},
"total_chunks": {
"type": "integer",
"minimum": 0
}
}
},
"ExtractMode": {
"type": "string",
"description": "Whether `remember()` extracts facts inline (sync) or defers to the\nasync extractor (Axtion / Observation grain). Per issue #538 R4 the\ncanonical API is `extract_mode`; the legacy `sync: bool` field on\ninterface request bodies is preserved for backward compatibility and\nmaps onto this enum.",
"enum": [
"async",
"sync"
]
},
"ExtractedChunk": {
"type": "object",
"description": "A single text chunk extracted from a document.",
"required": [
"content",
"char_offset"
],
"properties": {
"char_offset": {
"type": "integer",
"minimum": 0
},
"content": {
"type": "string"
},
"page": {
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0
},
"section": {
"type": [
"string",
"null"
]
},
"slide": {
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0
}
}
},
"FactsQuery": {
"type": "object",
"description": "Facts list query params.",
"properties": {
"after": {
"type": [
"string",
"null"
],
"description": "Cursor for keyset pagination (returned as `next_cursor` in previous response)."
},
"created_after": {
"type": [
"string",
"null"
],
"description": "Filter grains created after this ISO timestamp."
},
"created_before": {
"type": [
"string",
"null"
],
"description": "Filter grains created before this ISO timestamp."
},
"grain_type": {
"type": [
"string",
"null"
],
"description": "Filter by grain type (e.g. \"fact\", \"event\", \"tool\"). Case-insensitive."
},
"limit": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"offset": {
"type": [
"integer",
"null"
],
"description": "Pagination offset (legacy — prefer `after` cursor for infinite scroll).",
"minimum": 0
},
"query": {
"type": [
"string",
"null"
]
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "Sort field: \"created_at\" (default), \"confidence\", \"grain_type\"."
},
"subject": {
"type": [
"string",
"null"
]
}
}
},
"FileUploadBody": {
"type": "object",
"description": "Multipart file upload request body schema for OpenAPI documentation.",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload."
}
}
},
"FinalizeRunRequest": {
"type": "object",
"required": [
"run_id",
"outcome",
"grain_hashes"
],
"properties": {
"grain_hashes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to 256 grain hashes (hex-encoded SHA-256) participating in this run."
},
"outcome": {
"type": "string",
"description": "Outcome label — exactly `Confirmed`, `Failed`, or `Skipped` (case-sensitive).\n`Skipped` is a no-op for the EWMA update (carries no signal either way)."
},
"run_id": {
"type": "string",
"description": "Caller-supplied run identifier (1..=128 bytes, no ASCII control chars)."
}
}
},
"FinalizeRunResponse": {
"type": "object",
"required": [
"updated"
],
"properties": {
"updated": {
"type": "integer",
"description": "Number of grains whose pull-stats row was updated by this call.",
"minimum": 0
}
}
},
"ForgetRequest": {
"type": "object",
"description": "Forget request body (App format).",
"properties": {
"blob_hash": {
"type": [
"string",
"null"
]
},
"hashes": {
"type": "array",
"items": {
"type": "string"
}
},
"subject": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": [
"string",
"null"
]
}
}
},
"ForgetResponse": {
"type": "object",
"description": "Forget response.",
"required": [
"deleted",
"status"
],
"properties": {
"deleted": {
"type": "integer",
"minimum": 0
},
"status": {
"type": "string"
}
}
},
"GrainAction": {
"oneOf": [
{
"type": "object",
"description": "New chunk produced by the source — write a fresh grain. The\ncontent-address (SHA-256 of the canonical .mg payload) acts as the\nidempotency key, so re-running an apply is a no-op for already-\nwritten grains.",
"required": [
"new_grain_hash",
"preview",
"grain_type",
"grain_fields",
"kind"
],
"properties": {
"grain_fields": {
"type": "object",
"description": "Grain-field map forwarded to `Areev::add_from_json`."
},
"grain_type": {
"type": "string",
"description": "Grain-type discriminator forwarded to `Areev::add_from_json`\n(e.g. `\"fact\"`, `\"observation\"`)."
},
"kind": {
"type": "string",
"enum": [
"add"
]
},
"new_grain_hash": {
"type": "string",
"description": "Hash that the grain WILL have after write. Lets the UI show a\nstable preview reference."
},
"preview": {
"type": "string",
"description": "Short prose preview shown in the proposal-review modal."
}
}
},
{
"type": "object",
"description": "Existing grain is replaced by a new one. The applier writes the new\ngrain BEFORE setting `superseded_by` on the old one (so a crash\nbetween leaves new content reachable, not a dangling pointer).",
"required": [
"old_grain_hash",
"new_grain_hash",
"preview",
"reason",
"grain_type",
"grain_fields",
"kind"
],
"properties": {
"grain_fields": {
"type": "object"
},
"grain_type": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"supersede"
]
},
"new_grain_hash": {
"type": "string"
},
"old_grain_hash": {
"type": "string"
},
"preview": {
"type": "string"
},
"prior_preview": {
"type": [
"string",
"null"
],
"description": "Prose preview of the grain being replaced, so the review UI can\nshow before → after. Display-only — the applier ignores it."
},
"reason": {
"$ref": "#/components/schemas/SupersedeReason"
}
}
},
{
"type": "object",
"description": "Source file disappeared upstream. Schedules a `forget_user`-equivalent\ncascade scoped by `derived_from_knowledge_source_id`.",
"required": [
"old_grain_hash",
"preview",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"forget"
]
},
"old_grain_hash": {
"type": "string"
},
"preview": {
"type": "string"
}
}
}
],
"description": "One concrete grain mutation. The applier runs them in order: `Add`\nfirst, then `Supersede`, then `Forget`. Within a kind, order is the\norder they were generated by the delta computer.\n\n`Add` and `Supersede` carry the full new-grain payload (`grain_type`\n+ `grain_fields`) so the applier can call `Areev::add_from_json` /\n `supersede_from_json` directly. The trade-off: proposals are larger\n on disk (≈ chunk size × pending count), but apply is self-contained\n — no second round-trip to Axtion at approve time. Bounded by the\n per-KS pending cap (`MAX_PROPOSALS_PER_KS`) and the per-file size\n cap (100 MB at v1)."
},
"GrainListResponse": {
"type": "object",
"description": "Paginated grain list response.",
"required": [
"total",
"offset",
"limit",
"grains"
],
"properties": {
"grains": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GrainResponse"
}
},
"limit": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"total": {
"type": "integer",
"minimum": 0
}
}
},
"GrainResponse": {
"type": "object",
"description": "A grain in JSON form.",
"required": [
"hash",
"grain_type",
"fields"
],
"properties": {
"fields": {
"type": "object"
},
"grain_type": {
"type": "string"
},
"hash": {
"type": "string"
}
}
},
"GraphEdge": {
"type": "object",
"required": [
"subject",
"relation",
"object",
"grain_hash",
"confidence",
"grain_type",
"created_at"
],
"properties": {
"confidence": {
"type": "number",
"format": "double"
},
"created_at": {
"type": "integer",
"format": "int64"
},
"grain_hash": {
"type": "string"
},
"grain_type": {
"type": "string"
},
"object": {
"type": "string"
},
"relation": {
"type": "string"
},
"subject": {
"type": "string"
}
}
},
"GraphNode": {
"type": "object",
"required": [
"subject",
"out_degree",
"depth",
"grain_count"
],
"properties": {
"depth": {
"type": "integer",
"minimum": 0
},
"entity_type": {
"type": [
"string",
"null"
]
},
"grain_count": {
"type": "integer",
"minimum": 0
},
"out_degree": {
"type": "integer",
"minimum": 0
},
"subject": {
"type": "string"
}
}
},
"GraphQuery": {
"type": "object",
"properties": {
"depth": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"max_created_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Maximum grain created_at (epoch ms). Grains newer than this are excluded."
},
"max_nodes": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"min_confidence": {
"type": [
"number",
"null"
],
"format": "double"
},
"min_created_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Minimum grain created_at (epoch ms). Grains older than this are excluded."
},
"namespace": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
}
}
},
"GraphResponse": {
"type": "object",
"required": [
"nodes",
"edges",
"truncated",
"total_nodes_explored"
],
"properties": {
"edges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GraphEdge"
}
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GraphNode"
}
},
"predicate_classifications": {
"type": "object",
"description": "Per-relation cardinality classification keyed by the normalized\npredicate name. The UI uses this to render functional predicates\n(single-valued — `current_residence`, `date_of_birth`) differently\nfrom non-functional ones (`likes`, `knows`). Only includes relations\nthat appear on at least one edge in the response.",
"additionalProperties": {
"$ref": "#/components/schemas/PredicateClassification"
},
"propertyNames": {
"type": "string"
}
},
"total_nodes_explored": {
"type": "integer",
"minimum": 0
},
"truncated": {
"type": "boolean"
}
}
},
"HarnessChatRequest": {
"type": "object",
"required": [
"user_message",
"conversation_id"
],
"properties": {
"conversation_id": {
"type": "string",
"description": "Stable id for a multi-turn conversation. Event grains (OMS 1.2 §8.2)\nare written under `users/<uid>/harnesses/<slug>/conv/<conversation_id>`\nand carry `session_id = conversation_id` for CAL filtering."
},
"model": {
"type": [
"string",
"null"
],
"description": "LLM model override."
},
"provider": {
"type": [
"string",
"null"
],
"description": "LLM provider override (falls back to the memory's stored setting)."
},
"user_message": {
"type": "string"
}
}
},
"HarnessChatResponse": {
"type": "object",
"required": [
"text",
"harness_slug",
"conversation_id",
"system_prompt",
"tool_names",
"blocked_tools",
"tool_calls",
"iterations",
"assemble_params",
"input_tokens",
"output_tokens",
"provider",
"model",
"retrieval_ms",
"llm_ms",
"tools_ms"
],
"properties": {
"assemble_params": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"propertyNames": {
"type": "string"
}
},
"assistant_event_hash": {
"type": [
"string",
"null"
],
"description": "Content hash of the assistant-turn Event grain."
},
"blocked_tools": {
"type": "array",
"items": {
"type": "string"
}
},
"conversation_id": {
"type": "string"
},
"harness_slug": {
"type": "string"
},
"inline_tool_results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InlineToolResult"
},
"description": "Axtion tool results that ran inline in the same iteration as\nthe client-paused calls. Empty when no Axtion tool fired or\nwhen the turn reached `Completed` normally."
},
"input_tokens": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"iterations": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"llm_ms": {
"type": "integer",
"format": "int64",
"description": "Total wall-clock time spent on LLM provider calls across all turn\niterations.",
"minimum": 0
},
"model": {
"type": "string"
},
"output_tokens": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"pending_tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingToolCall"
},
"description": "Client-executed tool calls the caller must run and POST back.\nEmpty when `status == Completed`."
},
"provider": {
"type": "string"
},
"retrieval_ms": {
"type": "integer",
"format": "int64",
"description": "Total wall-clock time spent on CAL retrieval (recall of the harness\ndef namespace + memory-context assembly).",
"minimum": 0
},
"session_id": {
"type": [
"string",
"null"
],
"description": "Set when `status == RequiresAction`. Opaque id the caller posts\nback to `/chat/resume`. Generated server-side (not\nclient-supplied)."
},
"status": {
"$ref": "#/components/schemas/HarnessChatStatus",
"description": "`completed` for a terminal turn, `requires_action` when the cell\npauses on one or more `client://` tool calls."
},
"system_prompt": {
"type": "string"
},
"text": {
"type": "string"
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolCallTrace"
}
},
"tool_hashes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content hashes of the Tool grains written for each tool call,\nin the order the LLM emitted them."
},
"tool_names": {
"type": "array",
"items": {
"type": "string"
}
},
"tools_ms": {
"type": "integer",
"format": "int64",
"description": "Total wall-clock time spent on tool execution across all turn\niterations. Zero when the LLM called no tools.",
"minimum": 0
},
"user_event_hash": {
"type": [
"string",
"null"
],
"description": "Content hash of the user-turn Event grain (OMS 1.2 §8.2)."
}
}
},
"HarnessChatStatus": {
"type": "string",
"description": "Flow-A turn result — terminal (`Completed`) or paused\n(`RequiresAction`). Pauses carry a `session_id` + `pending_tool_calls`\nwhich the caller satisfies via `POST /chat/resume`.",
"enum": [
"completed",
"requires_action"
]
},
"HarnessConversationEntry": {
"type": "object",
"description": "One conversation summary returned by `list_harness_conversations`.",
"required": [
"conversation_id",
"title",
"preview",
"updated_at_ms",
"last_event_hash"
],
"properties": {
"conversation_id": {
"type": "string"
},
"last_event_hash": {
"type": "string"
},
"preview": {
"type": "string"
},
"title": {
"type": "string"
},
"updated_at_ms": {
"type": "integer",
"format": "int64"
}
}
},
"HarnessConversationListResponse": {
"type": "object",
"required": [
"conversations"
],
"properties": {
"conversations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HarnessConversationEntry"
}
}
}
},
"HarnessErrorResponse": {
"type": "object",
"description": "Harness-layer error envelope — `{code, message}` shape (F2 / FU-1).\n\nDistinct from the top-level `ErrorResponse` (`{error, code}`): the HPL\nhandlers emit `{code, message}` to match the error-code catalog + live\nwire behaviour. Attached to every 400/403/404/410/413 response on\n`chat/resume` and the 400/403/404 responses on\n`chat/sessions/{session_id}`.\n\n`HRN-E019` on `chat/resume` carries two extra optional fields —\n`tool_call_id` + `detail` — describing which pending-call output\nfailed validation and which validator rejected it (`shape`, `type`,\n`required`, `length`, `pattern`, `enum`, `depth`, `additional`,\n`size`). Other codes (`HRN-E015`, `HRN-E017`, `HRN-E018`, `HRN-E024`,\n`AUT-E003`, `MEM-E001`) only set `code` + `message`.",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Unified error code in `AAA-Ennn` format (e.g. `HRN-E015`,\n`HRN-E017`, `AUT-E003`). See `docs/facts/error-codes.md`.",
"example": "HRN-E015"
},
"detail": {
"type": "string",
"description": "Present only on `HRN-E019` schema-violation errors. Fixed-enum\nvalidator-failure token: one of `shape`, `type`, `required`,\n`length`, `pattern`, `enum`, `depth`, `additional`, `size`. The\noffending value itself is never reflected (SR B-7).",
"example": "required"
},
"message": {
"type": "string",
"description": "Human-readable, non-PII message. Never echoes caller-supplied\npayload content.",
"example": "chat session not found"
},
"tool_call_id": {
"type": "string",
"description": "Present only on `HRN-E019` schema-violation errors. The\n`tool_call_id` from the `pending_tool_calls` set whose output\nfailed validation. Safe to echo — bounded to the pending set.",
"example": "call_XYZ"
}
}
},
"HashResponse": {
"type": "object",
"description": "Standard success response with a hash.",
"required": [
"hash"
],
"properties": {
"hash": {
"type": "string"
}
}
},
"HealthResponse": {
"type": "object",
"description": "Health check response.",
"required": [
"status",
"name",
"version",
"description",
"interfaces",
"auth",
"load",
"backpressure_active",
"encryption",
"key_backend"
],
"properties": {
"active_searches": {
"type": [
"integer",
"null"
],
"description": "FR-004 #4: Number of recall operations currently in flight.\n`None` when --max-concurrent-searches is 0 (unlimited).",
"minimum": 0
},
"auth": {
"type": "string",
"description": "Active authentication mode: \"api-key\" | \"oidc\" | \"composite\".\nSurfaced here so developers can discover auth requirements from the health endpoint."
},
"backpressure_active": {
"type": "boolean",
"description": "FR-004 #3: Whether the search concurrency limit is fully saturated.\n`true` when all search permits are in use, `false` otherwise (including unlimited)."
},
"description": {
"type": "string"
},
"encryption": {
"type": "string",
"description": "Encryption status of the running server: \"active\" or \"none\".\nReports the actual server-side encryption state, unlike CLI `areev info`\nwhich opens a separate engine instance."
},
"import": {
"type": [
"object",
"null"
],
"description": "Import pipeline status. Present when `import` feature is enabled."
},
"interfaces": {
"type": "object"
},
"key_backend": {
"type": "string",
"description": "Key backend used by the server: \"vault\", \"local\", or \"none\"."
},
"key_rotation_age_days": {
"type": [
"integer",
"null"
],
"format": "int64",
"minimum": 0
},
"load": {
"type": "number",
"format": "double",
"description": "FR-004 #3: Search engine utilization ratio (0.0–1.0).\n`active_searches / max_concurrent_searches` when a semaphore is configured, `0.0` when unlimited."
},
"max_concurrent_searches": {
"type": [
"integer",
"null"
],
"description": "FR-004 #4: Maximum concurrent searches configured.\n`None` when unlimited.",
"minimum": 0
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"version": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Configuration warnings. Non-empty when compliance-relevant configuration is missing\n(e.g. no retention policy, no compliance policy set)."
}
}
},
"HookEventResponse": {
"type": "object",
"description": "A single CDC event in the response.",
"required": [
"seq",
"event_type",
"timestamp_ms"
],
"properties": {
"event_type": {
"type": "string"
},
"grain_count": {
"type": [
"integer",
"null"
],
"format": "int64",
"minimum": 0
},
"grain_type": {
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0
},
"hash": {
"type": [
"string",
"null"
]
},
"key_id": {
"type": [
"string",
"null"
]
},
"latency_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Webhook delivery latency in milliseconds. Set after successful delivery.",
"minimum": 0
},
"namespace": {
"type": [
"string",
"null"
]
},
"new_hash": {
"type": [
"string",
"null"
]
},
"object": {
"type": [
"string",
"null"
]
},
"old_hash": {
"type": [
"string",
"null"
]
},
"relation": {
"type": [
"string",
"null"
]
},
"seq": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"shard_id": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "D7.2: Shard ID that produced this event (distributed mode only).",
"minimum": 0
},
"subject": {
"type": [
"string",
"null"
]
},
"timestamp_ms": {
"type": "integer",
"format": "int64"
},
"user_id": {
"type": [
"string",
"null"
]
}
}
},
"HookEventsResponse": {
"type": "object",
"description": "CDC events response.",
"required": [
"events",
"count",
"head_seq",
"oldest_seq"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"cursors": {
"type": [
"object",
"null"
],
"description": "D7.2: Per-shard cursor positions after this response (distributed mode only).",
"additionalProperties": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"propertyNames": {
"type": "string"
}
},
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HookEventResponse"
}
},
"head_cursors": {
"type": [
"object",
"null"
],
"description": "D7.2: Per-shard head sequence numbers (distributed mode only).",
"additionalProperties": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"propertyNames": {
"type": "string"
}
},
"head_seq": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"oldest_seq": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"shard_errors": {
"type": [
"object",
"null"
],
"description": "D7.2: Per-shard errors for shards that failed (distributed mode only).\nValues are sanitized to generic messages (\"unreachable\", \"timeout\", \"not_leader\").",
"additionalProperties": {
"type": "string"
},
"propertyNames": {
"type": "string"
}
}
}
},
"HookResponse": {
"type": "object",
"description": "A single hook configuration (API response).",
"required": [
"hook_id",
"name",
"delivery_mode",
"status",
"event_filters",
"redaction_mode",
"delivery_count",
"failed_count",
"created_at",
"updated_at"
],
"properties": {
"axtion_trigger_id": {
"type": [
"string",
"null"
],
"description": "Axtion trigger ID (set after registering polling trigger in Axtion)."
},
"created_at": {
"type": "string"
},
"delivery_count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"delivery_mode": {
"type": "string",
"description": "Delivery mode: \"cdc\" or \"webhook\"."
},
"event_filters": {
"type": "array",
"items": {
"type": "string"
}
},
"failed_count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"hook_id": {
"type": "string"
},
"name": {
"type": "string"
},
"notification_summary": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/NotificationSummaryResponse",
"description": "Notification config summary (Axtion hooks only)."
}
]
},
"redaction_mode": {
"type": "string",
"description": "Redaction mode: \"full\", \"metadata_only\", or \"hash_only\"."
},
"secret": {
"type": [
"string",
"null"
],
"description": "HMAC signing secret — only returned once on create or rotate. Never persisted in responses."
},
"status": {
"type": "string",
"description": "Hook status: \"active\", \"paused\", \"failing\", or \"disabled\"."
},
"updated_at": {
"type": "string"
},
"url": {
"type": [
"string",
"null"
],
"description": "Webhook URL (omitted for CDC hooks, never includes secret)."
}
}
},
"HookStatsResponse": {
"type": "object",
"description": "Hook stats response.",
"required": [
"hook_count",
"event_count",
"head_seq",
"oldest_seq"
],
"properties": {
"event_count": {
"type": "integer",
"minimum": 0
},
"head_seq": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"hook_count": {
"type": "integer",
"minimum": 0
},
"oldest_seq": {
"type": "integer",
"format": "int64",
"minimum": 0
}
}
},
"HooksListResponse": {
"type": "object",
"description": "Hooks list response.",
"required": [
"hooks",
"count"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"hooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HookResponse"
}
}
}
},
"ImportConfigRequest": {
"type": "object",
"description": "Optional import configuration sent as a JSON part alongside the file.",
"properties": {
"chunk_min_size": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"chunk_overlap": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"chunk_size": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"confidence": {
"type": [
"number",
"null"
],
"format": "double"
},
"generate_summaries": {
"type": [
"boolean",
"null"
],
"description": "Generate LLM summaries for each section node. Default: true."
},
"grain_type": {
"type": [
"string",
"null"
]
},
"llm_structure": {
"type": [
"boolean",
"null"
],
"description": "Enable LLM-powered structure extraction for PDF/DOCX/PPTX. Default: true."
},
"max_tree_depth": {
"type": [
"integer",
"null"
],
"description": "Maximum tree depth for section hierarchy. Default: 6.",
"minimum": 0
},
"min_section_size": {
"type": [
"integer",
"null"
],
"description": "Minimum section size in characters. Default: 200.",
"minimum": 0
},
"namespace": {
"type": [
"string",
"null"
]
},
"source_uri": {
"type": [
"string",
"null"
],
"description": "Source URI for content_refs on generated grains."
},
"structured": {
"type": [
"boolean",
"null"
],
"description": "Enable structured (PageIndex-style) import: section tree + entity KG."
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"user_id": {
"type": [
"string",
"null"
]
}
}
},
"ImportDocumentResponse": {
"type": "object",
"description": "Import document response.",
"required": [
"filename",
"format",
"total_chunks",
"grains_added",
"chunks_skipped",
"grain_hashes",
"warnings",
"status"
],
"properties": {
"chunks_skipped": {
"type": "integer",
"minimum": 0
},
"filename": {
"type": "string"
},
"format": {
"type": "string"
},
"grain_hashes": {
"type": "array",
"items": {
"type": "string"
}
},
"grains_added": {
"type": "integer",
"minimum": 0
},
"pages_with_content": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Pages that produced extractable text content (PDF only).",
"minimum": 0
},
"status": {
"type": "string"
},
"total_chunks": {
"type": "integer",
"minimum": 0
},
"total_pages": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Total pages in the source document (PDF only).",
"minimum": 0
},
"tree_stats": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/TreeStatsResponse",
"description": "Structured import statistics. Absent when `structured` was not requested."
}
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ImportFileResponse": {
"type": "object",
"description": "Import file response.",
"required": [
"imported",
"skipped",
"status",
"filename"
],
"properties": {
"filename": {
"type": "string"
},
"imported": {
"type": "integer",
"minimum": 0
},
"skipped": {
"type": "integer",
"minimum": 0
},
"status": {
"type": "string"
}
}
},
"ImportRequest": {
"type": "object",
"description": "Import request body.",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "Directory path containing .mg files to import."
}
}
},
"ImportResponse": {
"type": "object",
"description": "Import result response.",
"required": [
"imported",
"skipped",
"errors"
],
"properties": {
"errors": {
"type": "integer",
"minimum": 0
},
"imported": {
"type": "integer",
"minimum": 0
},
"skipped": {
"type": "integer",
"minimum": 0
}
}
},
"InlineToolResult": {
"type": "object",
"description": "HPL Phase 4.4 — an inline tool result (Axtion executor) bubbled\nback to the caller when an Axtion call happens in the same turn as\npending client calls. Callers typically ignore these — they're\nalready reflected in the session's internal messages — but they\nsurface for debugging / observability parity.",
"required": [
"tool_call_id",
"tool_name",
"content",
"is_error"
],
"properties": {
"content": {
"type": "string"
},
"is_error": {
"type": "boolean"
},
"tool_call_id": {
"type": "string"
},
"tool_name": {
"type": "string"
}
}
},
"InvokeContentBlock": {
"oneOf": [
{
"type": "object",
"required": [
"text",
"type"
],
"properties": {
"text": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"text"
]
}
}
}
]
},
"InvokeRequest": {
"type": "object",
"required": [
"tool_name"
],
"properties": {
"arguments": {},
"extra_tools": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/ExtraToolDef"
},
"description": "Optional per-request overlay tool definitions. Each entry is\nvalidated against the same `SchemaValidator` the bind path uses\nand then layered over the durable harness catalogue for the\nlifetime of this request. Quota: ≤ 32 entries, each schema ≤\n16 KiB serialized JSON. Overlay tools never persist as\nDefinition grains."
},
"session_id": {
"type": [
"string",
"null"
],
"description": "Phase 6: opaque client-supplied session id. Session budgets +\n`final_answer` short-circuit are scoped by\n`(principal, session_id)`. Session state is deferred to Phase 6;\nv1 of this handler accepts + echoes the id but does not enforce\nbudgets."
},
"tool_call_id": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": "string"
}
}
},
"InvokeResponse": {
"oneOf": [
{
"type": "object",
"required": [
"result",
"audit_grain_id",
"status"
],
"properties": {
"audit_grain_id": {
"type": "string",
"description": "Hex hash of the persisted Execution Tool grain."
},
"result": {
"$ref": "#/components/schemas/InvokeResultBlock"
},
"session_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"completed"
]
}
}
},
{
"type": "object",
"required": [
"correlation_id",
"expires_at_sec",
"audit_grain_id",
"status"
],
"properties": {
"audit_grain_id": {
"type": "string",
"description": "Hex hash of the persisted Pending Execution Tool grain."
},
"correlation_id": {
"type": "string"
},
"expires_at_sec": {
"type": "integer",
"format": "int64"
},
"session_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"pending"
]
}
}
}
]
},
"InvokeResultBlock": {
"type": "object",
"required": [
"content",
"is_error"
],
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvokeContentBlock"
}
},
"is_error": {
"type": "boolean"
},
"structured_content": {}
}
},
"KnowledgeSource": {
"type": "object",
"description": "A persisted Knowledge Source binding.",
"required": [
"ks_id",
"memory_id",
"name",
"connector_name",
"connector_display_name",
"connection_id",
"scope",
"sync_policy",
"status",
"created_at_ms",
"created_by"
],
"properties": {
"account_email": {
"type": [
"string",
"null"
],
"description": "Provider account label (e.g. Gmail address) — denormalised from the\nconnection at create time so the UI can disambiguate sources without a join."
},
"axtion_trigger_id": {
"type": [
"string",
"null"
],
"description": "Trigger ID returned by Axtion when polling/webhook is registered.\n`None` until the first sync completes successfully."
},
"callback_secret": {
"type": [
"string",
"null"
],
"description": "Per-trigger HMAC secret; the cell verifies the callback HMAC against\nit. Stays serializable for encrypted at-rest persistence — never add\n`#[serde(skip_serializing)]` (drops it from the store, breaks\nverification). SECURITY: never expose in any API response — HTTP\nhandlers MUST serialize `KnowledgeSource::redacted()`."
},
"connection_id": {
"type": "string",
"description": "Reference into the existing `connections` partition. The actual OAuth\ncredential lives in Axtion's encrypted vault, never in Areev."
},
"connector_display_name": {
"type": "string",
"description": "Human-readable connector label — e.g. `\"Google Drive\"`."
},
"connector_name": {
"type": "string",
"description": "Axtion connector identifier — e.g. `\"google_drive\"`, `\"notion\"`."
},
"created_at_ms": {
"type": "integer",
"format": "int64"
},
"created_by": {
"type": "string",
"description": "User principal that created the KS. Used for audit + GDPR Art. 17 cascade."
},
"ks_id": {
"type": "string",
"description": "ULID — primary key within `(memory_id, ks_id)`."
},
"last_synced_at_ms": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"memory_id": {
"type": "string"
},
"name": {
"type": "string",
"description": "User-facing label, e.g. `\"Q3 Strategy Documents\"`."
},
"scope": {
"$ref": "#/components/schemas/KsScope",
"description": "What's selected from the source."
},
"status": {
"$ref": "#/components/schemas/KsStatus"
},
"sync_policy": {
"$ref": "#/components/schemas/SyncPolicy",
"description": "How the KS keeps in sync. v0 forces manual sync; v1 enables polling."
}
}
},
"KnowledgeSourceResponse": {
"type": "object",
"description": "Response body for single-KS endpoints (get / create / update).",
"required": [
"knowledge_source"
],
"properties": {
"knowledge_source": {
"$ref": "#/components/schemas/KnowledgeSource"
}
}
},
"KnowledgeSourcesListResponse": {
"type": "object",
"description": "Response body for `GET /knowledge-sources` (list).",
"required": [
"knowledge_sources"
],
"properties": {
"knowledge_sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeSource"
}
}
}
},
"KsFile": {
"type": "object",
"description": "One file in a KS scope.",
"required": [
"source_file_id",
"name",
"mime_type",
"etag"
],
"properties": {
"etag": {
"type": "string",
"description": "Connector-specific version identifier (etag, revision_id, last_edited_time, …)."
},
"last_content_sha256": {
"type": [
"string",
"null"
],
"description": "SHA-256 (hex) of the bytes imported at the last successful sync.\nDrives the manual-Sync skip-unchanged path."
},
"last_sync_error": {
"type": [
"string",
"null"
],
"description": "Last sync error string (only populated when `last_sync_status == Failed`)."
},
"last_sync_status": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/KsFileStatus",
"description": "Last sync outcome — drives the per-row status badge in the UI."
}
]
},
"last_synced_at_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Wall-clock ms of the most recent successful or failed sync of this file."
},
"last_synced_etag": {
"type": [
"string",
"null"
],
"description": "etag at the last successful sync — reserved for CDC dedup."
},
"mime_type": {
"type": "string"
},
"name": {
"type": "string"
},
"size_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Optional size in bytes for UI / capacity-cap enforcement.",
"minimum": 0
},
"source_file_id": {
"type": "string",
"description": "Connector-specific opaque file ID."
}
}
},
"KsFileStatus": {
"type": "string",
"description": "Per-file sync status, kept on `KsFile`.",
"enum": [
"synced",
"failed",
"pending"
]
},
"KsScope": {
"type": "object",
"description": "What chunk of the source the KS pulls from.",
"properties": {
"cloud_id": {
"type": [
"string",
"null"
],
"description": "DEPRECATED — pre-`ConnectorMeta` records persisted `cloud_id` here.\nMigrated into `meta` on read by `migrate_legacy_meta`; new writes\nomit this field. Kept to deserialize old records cleanly."
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KsFile"
},
"description": "Explicitly selected files. v0 supports this only."
},
"folder_root": {
"type": [
"string",
"null"
],
"description": "Optional folder root for recursive sync (v1)."
},
"max_depth": {
"type": "integer",
"format": "int32",
"description": "Recursion depth cap. Default 5, hard max 10.",
"minimum": 0
},
"meta": {
"$ref": "#/components/schemas/ConnectorMeta",
"description": "Typed per-connector state (e.g. Atlassian Cloud ID for `confluence`).\nOwned by the connector module; the orchestrator never reads its\ncontents directly. Default `None` for connectors that need no state."
},
"recursive": {
"type": "boolean",
"description": "Whether to sync subfolders. v0: ignored."
}
}
},
"KsStatus": {
"type": "string",
"description": "Lifecycle state of a KS.",
"enum": [
"draft",
"indexing",
"indexed",
"partial_failure",
"needs_update",
"auth_expired",
"failed",
"archived"
]
},
"ListGrainsQuery": {
"type": "object",
"description": "Grain list query parameters.",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"offset": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
},
"ListResponse": {
"type": "object",
"description": "List of strings response (namespaces, users).",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"items": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"LlmSettingsResponse": {
"type": "object",
"description": "Response for GET /api/settings/llm — the raw api_key is never returned.",
"required": [
"provider",
"model",
"api_key_set"
],
"properties": {
"api_key_set": {
"type": "boolean",
"description": "True if an API key has been stored; the key value is never returned."
},
"base_url": {
"type": [
"string",
"null"
]
},
"connection_status": {
"type": [
"string",
"null"
],
"description": "Connection status: \"connected\", \"unavailable\", or null if not checked."
},
"model": {
"type": "string"
},
"provider": {
"type": "string"
}
}
},
"MemoriesListResponse": {
"type": "object",
"description": "List of memories.",
"required": [
"memories",
"count",
"has_more"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"has_more": {
"type": "boolean"
},
"memories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemoryResponse"
}
},
"offset": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"total": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
},
"MemoryMeta": {
"type": "object",
"description": "Metadata for a single memory (persisted to memories.json).",
"required": [
"id",
"name",
"created_at",
"subdir",
"org_id"
],
"properties": {
"cell_id": {
"type": [
"string",
"null"
],
"description": "Cell that owns this memory's grain data.\nNone in edge/node/single-cell mode."
},
"created_at": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"org_id": {
"type": "string",
"description": "Organization ID that owns this memory. Every memory belongs to exactly one org."
},
"policy": {
"type": [
"string",
"null"
]
},
"region_id": {
"type": [
"string",
"null"
],
"description": "Region where this memory's data resides (for data sovereignty).\nNone in edge/node mode."
},
"subdir": {
"type": "string",
"description": "Relative path under data_dir where this memory's Areev store lives."
}
}
},
"MemoryResponse": {
"type": "object",
"description": "Memory descriptor (App API).",
"required": [
"id",
"name",
"created_at",
"total_grains",
"namespaces",
"agents"
],
"properties": {
"active_imports": {
"type": [
"integer",
"null"
],
"description": "Number of active import jobs for this memory.",
"minimum": 0
},
"agents": {
"type": "integer",
"description": "Number of unique agent identifiers seen across all grains (computed from the agent index).",
"minimum": 0
},
"created_at": {
"type": "string",
"description": "ISO 8601 creation timestamp."
},
"dedup": {
"type": [
"string",
"null"
],
"description": "Write-path dedup policy: \"none\", \"exact\", \"fuzzy\", \"upsert\"."
},
"description": {
"type": [
"string",
"null"
],
"description": "Optional description."
},
"guardrail_rules_count": {
"type": [
"integer",
"null"
],
"description": "Number of active guardrail rules.",
"minimum": 0
},
"id": {
"type": "string",
"description": "Unique memory identifier (slugified from name)."
},
"name": {
"type": "string",
"description": "Human-readable name."
},
"namespaces": {
"type": "integer",
"description": "Number of distinct namespaces (computed from the namespace index).",
"minimum": 0
},
"policy_preset": {
"type": [
"string",
"null"
],
"description": "Policy preset if one is applied (e.g. \"gdpr\", \"hipaa\", \"default\")."
},
"status": {
"type": [
"string",
"null"
],
"description": "Memory status: \"active\" or \"idle\"."
},
"store_size": {
"type": [
"string",
"null"
],
"description": "Human-readable on-disk store size (e.g. \"12.4 MB\"). Computed from Fjall partition sizes."
},
"total_grains": {
"type": "integer",
"description": "Total number of grains stored (computed at query time from the grain index).",
"minimum": 0
}
}
},
"ModelAssignmentsResponse": {
"type": "object",
"description": "GET /api/settings/model-assignments response.",
"properties": {
"chat": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
},
"embed": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
},
"import": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
},
"rerank": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
}
}
},
"ModelCapability": {
"type": "string",
"enum": [
"chat",
"rerank",
"import",
"embed",
"chat_tool_use"
]
},
"ModelInfo": {
"type": "object",
"description": "A model available from a provider.",
"required": [
"id",
"name",
"provider_id",
"provider_type",
"capabilities",
"accessible",
"supports_temperature"
],
"properties": {
"accessible": {
"type": "boolean",
"description": "Whether the caller's tier permits dispatching this model. Always\n`true` on self-hosted (`metrics-cloud-billing` disabled) and for\nnon-allowlisted models."
},
"capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelCapability"
}
},
"context_window": {
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0
},
"id": {
"type": "string"
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0
},
"name": {
"type": "string"
},
"provider_id": {
"type": "string"
},
"provider_type": {
"$ref": "#/components/schemas/ProviderType"
},
"supports_temperature": {
"type": "boolean",
"description": "`false` for OpenAI reasoning families that reject custom temperature."
},
"tier_required": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelTier",
"description": "Tier required to dispatch this model. `None` for non-allowlisted\n(operator-managed) models — tier-gating is scoped to the curated set."
}
]
}
}
},
"ModelRef": {
"type": "object",
"description": "Reference to a specific model on a specific provider.",
"required": [
"provider_id",
"model"
],
"properties": {
"model": {
"type": "string"
},
"provider_id": {
"type": "string"
}
}
},
"ModelTier": {
"type": "string",
"description": "Subscription tier required to dispatch a model in Memory Explorer chat.\n\nHierarchical: `Custom > Scale > Free`. Higher tiers transitively unlock\nlower tiers via [`ModelTier::includes`]. The Pilot session token's\nversioned `tier_id` (`f1`/`s1`/`c1`) maps onto this enum via\n[`ModelTier::from_tier_id`] — the major-version letter is the\nauthoritative classifier so future minor revs (`f2`, `s3`) map without\ncode changes.",
"enum": [
"free",
"scale",
"custom"
]
},
"ModelsResponse": {
"type": "object",
"description": "GET /api/models response — unified model list across all providers.",
"required": [
"models"
],
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelInfo"
}
}
}
},
"NotificationSummaryResponse": {
"type": "object",
"description": "Summary of configured notification action (Axtion hooks only).\n\nIncludes `params` + `params_transform` so the UI can render an \"Edit\ndestination\" flow with pre-filled values. The endpoint is already gated\nby `get_memory_org_checked` admin auth, so exposing params here matches\nthe existing PUT path's authorization surface.",
"required": [
"connector",
"connector_name",
"action",
"action_name"
],
"properties": {
"action": {
"type": "string"
},
"action_name": {
"type": "string"
},
"connector": {
"type": "string"
},
"connector_name": {
"type": "string"
},
"params": {
"type": "object"
},
"params_transform": {
"type": [
"string",
"null"
]
}
}
},
"OAuthProviderInfo": {
"type": "object",
"description": "Public OAuth provider info returned in /api/config.\nOnly exposes the client_id (public), never the secret.",
"required": [
"provider",
"client_id"
],
"properties": {
"client_id": {
"type": "string"
},
"provider": {
"type": "string"
}
}
},
"ParseError": {
"type": "object",
"description": "A non-fatal parse error — a malformed tool call that was skipped.\nMultiple may appear alongside successfully-parsed calls.",
"required": [
"reason"
],
"properties": {
"position": {
"type": [
"integer",
"null"
],
"description": "Byte offset of the start of the malformed region when known.",
"minimum": 0
},
"reason": {
"type": "string"
}
}
},
"ParseRequest": {
"type": "object",
"required": [
"format",
"raw_output"
],
"properties": {
"format": {
"type": "string",
"description": "Wire-format name: `hermes`, `llama31`, `anthropic-tools`,\n`openai-tools`, `openai-responses`, `markdown-tools`."
},
"raw_output": {
"type": "string",
"description": "Raw LLM output to parse. Capped at 1 MB."
}
}
},
"ParseResponse": {
"type": "object",
"required": [
"tool_calls",
"errors"
],
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParseError"
}
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParsedToolCall"
}
}
}
},
"ParsedToolCall": {
"type": "object",
"description": "A successfully parsed tool call.",
"required": [
"id",
"name",
"arguments"
],
"properties": {
"arguments": {
"description": "Parsed arguments object — never a JSON-encoded string, even for\nOpenAI (which emits arguments as a JSON string on the wire)."
},
"id": {
"type": "string",
"description": "Call identifier — populated from provider output when available,\notherwise generated as `call_{index}`."
},
"name": {
"type": "string",
"description": "Tool name (as emitted by the provider; caller may re-normalize)."
}
}
},
"PendingToolCall": {
"type": "object",
"description": "HPL Phase 4.4 — one client-executed tool call the caller must run.\nEchoed back in the suspend response; `tool_call_id` is the LLM's\nidentifier and is what the resume body must reference.",
"required": [
"tool_call_id",
"tool_name",
"arguments"
],
"properties": {
"arguments": {
"type": "string"
},
"tool_call_id": {
"type": "string"
},
"tool_name": {
"type": "string"
}
}
},
"PiiMatchResponse": {
"type": "object",
"description": "A single PII/PHI match with position and confidence.",
"required": [
"category",
"matched_text",
"start",
"end",
"confidence",
"source"
],
"properties": {
"category": {
"type": "string"
},
"confidence": {
"type": "number",
"format": "float"
},
"end": {
"type": "integer",
"minimum": 0
},
"matched_text": {
"type": "string"
},
"source": {
"type": "string"
},
"start": {
"type": "integer",
"minimum": 0
}
}
},
"PiiResponse": {
"type": "object",
"description": "PII detection response.",
"required": [
"detections"
],
"properties": {
"detections": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"PolicyAppResponse": {
"type": "object",
"description": "Policy response.",
"required": [
"policy"
],
"properties": {
"policy": {
"type": "object"
}
}
},
"PolicyEnforceRequest": {
"type": "object",
"description": "Request to enforce a specific policy control on existing data.",
"required": [
"control"
],
"properties": {
"control": {
"type": "string",
"description": "Which control to enforce: \"encryption\", \"ttl\", \"pii_scan\", \"consent_status\"."
}
}
},
"PolicyModifyRequest": {
"type": "object",
"description": "Request to modify an active memory's policy (hot-reload).",
"properties": {
"add_policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Policies to add (e.g. [\"gdpr\", \"hipaa\"])."
},
"downgrade_reason": {
"type": [
"string",
"null"
],
"description": "Required when removing policies — rationale for downgrade."
},
"remove_policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Policies to remove (e.g. [\"default\"])."
}
}
},
"PolicyModifyResponse": {
"type": "object",
"description": "Response after a successful policy modification.",
"required": [
"version",
"policies",
"config_hash",
"updated_at"
],
"properties": {
"config_hash": {
"type": "string"
},
"policies": {
"type": "array",
"items": {
"type": "string"
}
},
"updated_at": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 0
}
}
},
"PolicyResidencyRequest": {
"type": "object",
"description": "`PUT /memories/{id}/policy/residency` request (issue #570). Admin-scoped.",
"properties": {
"allowed_regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Region ids data may physically reside in (e.g. `[\"sg\"]`). An empty list\nunder `enforce` denies every region (fail-closed)."
},
"enforcement": {
"type": [
"string",
"null"
],
"description": "`\"enforce\"` (default) or `\"disabled\"`."
}
}
},
"PolicyResidencyResponse": {
"type": "object",
"description": "Response for the residency set/clear endpoints (issue #570).",
"required": [
"memory_id",
"config_hash",
"updated_at"
],
"properties": {
"config_hash": {
"type": "string",
"description": "SHA-256 config hash from the (re-sealed) PolicySeal."
},
"data_residency": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DataResidencyView",
"description": "The residency override now in effect, or `None` after a clear."
}
]
},
"memory_id": {
"type": "string"
},
"updated_at": {
"type": "string",
"description": "Server timestamp of the update (ISO 8601)."
}
}
},
"PolicyResolvedResponse": {
"type": "object",
"description": "Resolved policy projection — strict subset of `get_policy` data, pre-computed\nfor callers that need the strictest-policy summary (e.g. HIPAA hard-block checks).",
"required": [
"memory_id",
"policy",
"policy_set",
"consent_level",
"config_hash",
"resolved_at"
],
"properties": {
"config_hash": {
"type": "string",
"description": "SHA-256 config hash from the PolicySeal."
},
"consent_level": {
"type": "string",
"description": "Resolved consent level (\"none\", \"opt_out\", \"explicit\")."
},
"data_residency": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/DataResidencyView",
"description": "Data-residency override, if one is attached to the seal (issue #570).\n`None` for every preset by default — operator opt-in only."
}
]
},
"memory_id": {
"type": "string",
"description": "Memory ID this projection belongs to."
},
"policy": {
"type": "string",
"description": "Strictest active policy (e.g. \"hipaa\")."
},
"policy_set": {
"type": "array",
"items": {
"type": "string"
},
"description": "All active policies, ordered strictest-first."
},
"resolved_at": {
"type": "string",
"description": "Server timestamp when this projection was computed (ISO 8601)."
},
"ttl_days": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Shortest TTL across active policies (days), if any.",
"minimum": 0
}
}
},
"PolicySimulateRequest": {
"type": "object",
"description": "Policy simulate request body.\n\nSimulates the impact of changing to a new policy configuration without applying it.",
"required": [
"target_policy"
],
"properties": {
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of regulation names to simulate (e.g. [\"gdpr\", \"hipaa\"])."
},
"sample_content": {
"type": [
"string",
"null"
],
"description": "Optional sample content to test PII/PHI detection under the new policy."
},
"target_policy": {
"type": "object",
"description": "Target policy preset name (e.g. \"gdpr\", \"hipaa\", \"default\") or a full policy config object."
}
}
},
"PolicySimulationResponse": {
"type": "object",
"description": "Policy simulation response.",
"required": [
"memories_affected",
"would_require_consent",
"would_encrypt",
"would_decrypt",
"would_delete",
"consent_gaps",
"policy_diff"
],
"properties": {
"consent_gaps": {
"type": "integer",
"minimum": 0
},
"memories_affected": {
"type": "integer",
"minimum": 0
},
"policy_diff": {
"type": "object"
},
"would_decrypt": {
"type": "integer",
"minimum": 0
},
"would_delete": {
"type": "integer",
"minimum": 0
},
"would_encrypt": {
"type": "integer",
"minimum": 0
},
"would_require_consent": {
"type": "integer",
"minimum": 0
}
}
},
"Precedence": {
"type": "string",
"description": "How conflicts between grains at different scope depths are resolved.",
"enum": [
"authoritative",
"deferring",
"additive"
]
},
"PredicateClassification": {
"type": "object",
"description": "Cardinality info for a single predicate. Surfaced on graph responses so\nthe UI can style edges by source (built-in static / learned / unknown).",
"required": [
"is_functional",
"source"
],
"properties": {
"is_functional": {
"type": "boolean"
},
"source": {
"type": "string",
"description": "One of: `static_functional`, `static_non_functional`,\n`learned_functional`, `learned_non_functional`, `unknown`."
}
}
},
"PredicateHintRequest": {
"type": "object",
"description": "Request body for the predicate-hint ingestion endpoint. Submitted by the\nFact extractor (Axtion) when it has a confident classification of a\npredicate it just emitted.",
"required": [
"relation",
"hint",
"confidence",
"user_id"
],
"properties": {
"confidence": {
"type": "number",
"format": "float",
"description": "LLM confidence [0.0, 1.0]."
},
"hint": {
"type": "string",
"description": "Cardinality classification: `\"functional\"` or `\"non_functional\"`."
},
"relation": {
"type": "string",
"description": "The relation/predicate being classified (e.g. \"current_employer\")."
},
"user_id": {
"type": "string",
"description": "User this Fact was extracted on behalf of. Pseudonymized server-side\nbefore storage; the raw value never enters the learned vocabulary log."
}
}
},
"PreferenceResponse": {
"type": "object",
"description": "GET /api/preferences/{key} response — a single preference.",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string"
},
"value": {}
}
},
"PreferencesResponse": {
"type": "object",
"description": "GET /api/preferences response — all preferences for the authenticated user.",
"required": [
"preferences"
],
"properties": {
"preferences": {
"type": "object",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
}
}
},
"ProposalStatus": {
"type": "string",
"description": "Lifecycle state of a `ChangeProposal`. Transitions are documented at\nthe module level.",
"enum": [
"pending",
"approving",
"applying",
"applied",
"rejected",
"apply_failed",
"expired",
"superseded",
"auto_applied"
]
},
"ProposalsListResponse": {
"type": "object",
"description": "Response body for `GET /knowledge-sources/{ks_id}/proposals`.",
"required": [
"proposals"
],
"properties": {
"proposals": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChangeProposal"
}
}
}
},
"ProvenanceListQuery": {
"type": "object",
"description": "Provenance list query params.",
"properties": {
"enrich": {
"type": [
"boolean",
"null"
],
"description": "When true, hydrate each returned_hash with grain type + content summary.\nGrains are fetched from cache/disk on the fly (not stored in provenance)."
},
"from": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"limit": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"min_results": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Exclude recalls whose `result_count` is below this threshold. Default: 0 (no filter).\nPass `1` to hide empty recalls (e.g. chat auto-recalls that returned no matches).",
"minimum": 0
},
"namespace": {
"type": [
"string",
"null"
]
},
"offset": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"to": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
},
"ProvenanceListResponse": {
"type": "object",
"description": "Provenance list response.",
"required": [
"records",
"count",
"total",
"truncated",
"fetch_cap"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"fetch_cap": {
"type": "integer",
"description": "Upper bound on the raw fetch when `min_results > 0` (10_000).\nExposed so clients can render \"10k+\" UX.",
"minimum": 0
},
"records": {
"type": "array",
"items": {
"type": "object"
}
},
"total": {
"type": "integer",
"description": "Total matching records across the queried window. When\n`min_results > 0`, counted in-memory from the filtered set\n(bounded by `fetch_cap`); otherwise computed via\n`count_provenance`.",
"minimum": 0
},
"truncated": {
"type": "boolean",
"description": "`true` when `min_results > 0` and the raw fetch saturated\n`fetch_cap` — `total` is then a lower bound on the true match\ncount. Callers should page or narrow the window to see more."
}
}
},
"ProvenanceSummaryResponse": {
"type": "object",
"description": "Provenance summary statistics.",
"required": [
"total_recalls",
"avg_sources_per_recall",
"avg_latency_ms",
"scoring_method"
],
"properties": {
"avg_latency_ms": {
"type": "number",
"format": "double"
},
"avg_sources_per_recall": {
"type": "number",
"format": "double"
},
"scoring_method": {
"type": "string"
},
"total_recalls": {
"type": "integer",
"minimum": 0
}
}
},
"ProviderListResponse": {
"type": "object",
"description": "GET /api/settings/providers response.",
"required": [
"catalog",
"custom",
"policy"
],
"properties": {
"catalog": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogProviderSummary"
}
},
"custom": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomProviderSummary"
}
},
"policy": {
"$ref": "#/components/schemas/ProviderPolicy"
}
}
},
"ProviderModelsResponse": {
"type": "object",
"description": "GET /api/settings/providers/{provider_id}/models response.",
"required": [
"provider_id",
"models"
],
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelInfo"
}
},
"provider_id": {
"type": "string"
}
}
},
"ProviderPolicy": {
"type": "string",
"description": "Determines which provider operations are allowed based on build profile.",
"enum": [
"disabled",
"platform_managed",
"catalog_plus_custom"
]
},
"ProviderPolicyResponse": {
"type": "object",
"description": "GET /api/settings/provider-policy response.",
"required": [
"policy"
],
"properties": {
"policy": {
"$ref": "#/components/schemas/ProviderPolicy"
}
}
},
"ProviderStatus": {
"oneOf": [
{
"type": "object",
"description": "Provider is in catalog but not yet configured (no credentials).",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"unconfigured"
]
}
}
},
{
"type": "object",
"description": "Provider has credentials and has been tested successfully.",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"ready"
]
}
}
},
{
"type": "object",
"description": "Provider has credentials but the last test failed.",
"required": [
"message",
"state"
],
"properties": {
"message": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"error"
]
}
}
}
],
"description": "Lifecycle status of a configured provider."
},
"ProviderType": {
"type": "string",
"description": "Supported LLM provider types.\n\nExtended from original 7 to 13 variants. Each variant maps to a known API\nprotocol and default base URL. `Custom` is for user-defined OpenAI-compatible\nendpoints (self-hosted only).",
"enum": [
"openai",
"anthropic",
"ollama",
"huggingface",
"openrouter",
"google",
"groq",
"together",
"mistral",
"deepseek",
"azure_openai",
"aws_bedrock",
"custom"
]
},
"ProvisionRequest": {
"type": "object",
"description": "Request body for POST /harnesses/{slug}/provision.",
"required": [
"template_id"
],
"properties": {
"template_id": {
"type": "string",
"description": "Template ID from `baseline_templates()`."
}
}
},
"ProvisionResponse": {
"type": "object",
"required": [
"provisioned",
"goal_hash",
"actions_written"
],
"properties": {
"actions_written": {
"type": "integer",
"format": "int32",
"description": "Number of Tool grains written (0 — Tools are advisory in M1).",
"minimum": 0
},
"goal_hash": {
"type": "string",
"description": "Hash of the Goal grain written (or already existing)."
},
"provisioned": {
"type": "boolean",
"description": "Whether provisioning wrote new grains (true) or all grains\nalready existed (false — idempotent repeat)."
}
}
},
"PullStatsRecord": {
"type": "object",
"description": "OpenAPI-only schema for a single pull-stats record (matches the JSON\nproduced by `pull_stats_view_to_json`).\n\nThe handlers return `serde_json::Value` directly so the timestamp fields\ncan be `null` or RFC3339 strings; this struct gives utoipa a concrete\nschema to advertise to clients.",
"required": [
"hash",
"pull_count",
"distinct_run_pull_count"
],
"properties": {
"distinct_run_pull_count": {
"type": "integer",
"format": "int64",
"description": "Number of distinct `run_id` values that have pulled this grain.",
"minimum": 0
},
"first_pull_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "First-pull timestamp as RFC3339, or `null` when never pulled."
},
"hash": {
"type": "string",
"description": "Hex-encoded SHA-256 of the grain blob."
},
"last_pulled_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Last-pull timestamp as RFC3339, or `null` when never pulled."
},
"outcome_weighted_pull_score": {
"type": [
"number",
"null"
],
"format": "double",
"description": "EWMA-weighted score derived from finalize-run outcomes; `null` when unset."
},
"pull_count": {
"type": "integer",
"format": "int64",
"description": "Total successful pulls observed across all runs.",
"minimum": 0
},
"reuse_half_life_seconds": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Half-life (seconds) used to decay reuse scores; `null` when unset."
}
}
},
"PurgeNamespaceBody": {
"type": "object",
"properties": {
"reason": {
"type": [
"string",
"null"
],
"description": "Authorisation rationale (SOC 2 CC8.1). Required when `force=true`.\nValidated by the engine: ≤512 chars, no secret patterns, no PII."
}
}
},
"RecallAppRequest": {
"type": "object",
"description": "Recall request body (App format).\n\n`deny_unknown_fields` makes spelling mistakes (e.g. `grain_types` vs\n`grain_type`, or `types` vs `grain_type`) fail fast at deserialization\ninstead of silently slipping past serde and producing unfiltered\nresults. The `JsonBody` extractor maps the resulting `JsonDataError`\nto HTTP 422 with a generic body (DX-P0-1 / CU-86d2x2qd1 — Rust field\nnames and byte offsets are not echoed to clients); the exact offending\nfield name is logged via `tracing::warn!` under target\n`areev::server::routes`, kind `JsonDataError`, for operator diagnosis.",
"properties": {
"aggregation_intent": {
"type": [
"boolean",
"null"
],
"description": "RQ-3: Keep superseded grains at natural scores for aggregation queries."
},
"annotate_relative_time": {
"type": [
"boolean",
"null"
],
"description": "Annotate each result with a human-readable relative time label (e.g., \"2 weeks ago\")."
},
"candidate_limit": {
"type": [
"integer",
"null"
],
"description": "Two-stage retrieval: candidate count for first stage.",
"minimum": 0
},
"confidence_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Minimum confidence threshold [0.0–1.0]."
},
"conflict_resolution": {
"type": [
"boolean",
"null"
],
"description": "FR-A004: Keep only the newest grain when same (subject, relation) has different objects.\nIndependent of detect_contradictions."
},
"conflict_similarity_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Conflict similarity threshold [0.0–1.0] for conflict_resolution."
},
"count_entities": {
"type": [
"boolean",
"null"
],
"description": "Count distinct entities (subjects) in results and include in response."
},
"deduplicate": {
"type": [
"boolean",
"null"
],
"description": "Deduplicate grains with similar (subject, relation, object) using string similarity."
},
"deduplicate_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Similarity threshold for deduplication (0.0–1.0, default 0.85)."
},
"detect_contradictions": {
"type": [
"boolean",
"null"
],
"description": "Apply interference detection and penalize contradicted grains."
},
"diversity": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Diversity reranking: MMR lambda [0.0–1.0]. 1.0=pure relevance, 0.0=max diversity."
},
"embedding": {
"type": [
"array",
"null"
],
"items": {
"type": "number",
"format": "float"
},
"description": "Pre-computed embedding vector for KNN semantic search."
},
"entity": {
"type": [
"string",
"null"
],
"description": "FR-A007: Entity-centric recall — find all grains where this entity\nappears as either subject or object."
},
"exclude_superseded": {
"type": [
"boolean",
"null"
],
"description": "Exclude superseded grains from results (default: true in engine)."
},
"exclude_tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Exclude tags filter — grains with any of these tags are excluded."
},
"exhaustive": {
"type": [
"boolean",
"null"
],
"description": "WI-EXHAUST: Enable exhaustive entity-class recall for aggregation/counting queries.\nIteratively expands entity coverage using synonyms and hexastore lookups (2-5x latency)."
},
"exhaustive_max_rounds": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "WI-EXHAUST: Maximum expansion rounds for exhaustive recall (1-5, default 3).",
"minimum": 0
},
"explain": {
"type": [
"boolean",
"null"
]
},
"explanation": {
"type": [
"boolean",
"null"
],
"description": "EU AI Act Art. 86: Include human-readable explanation per result."
},
"grain_type": {
"type": [
"string",
"null"
],
"description": "Filter by grain type (fact, event, state, workflow, tool, observation, goal, reasoning, consensus, consent, skill)."
},
"hyde": {
"type": [
"boolean",
"null"
],
"description": "FR-A008 Phase 2: Enable HyDE (Hypothetical Document Embeddings)."
},
"importance_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Minimum importance threshold [0.0–1.0]."
},
"include_siblings": {
"type": [
"boolean",
"null"
],
"description": "Scoped memory: include sibling namespaces at the same depth."
},
"include_sources": {
"type": [
"boolean",
"null"
],
"description": "Include source grains for results that have `derived_from` links."
},
"limit": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"max_namespaces": {
"type": [
"integer",
"null"
],
"description": "FR-005: Maximum unique namespaces in results.\nAlso accepts `max_sessions` (sessions are namespaces in Areev's data model).",
"minimum": 0
},
"min_per_namespace": {
"type": [
"integer",
"null"
],
"description": "FR-005: Minimum grains per namespace for cross-session coverage.\nAlso accepts `min_per_session` (sessions are namespaces in Areev's data model).",
"minimum": 0
},
"min_score": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Minimum score threshold [0.0–1.0] — results below this are dropped."
},
"multi_hop": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Entity-graph multi-hop retrieval depth (1–3).",
"minimum": 0
},
"namespace": {
"type": [
"string",
"null"
]
},
"object": {
"type": [
"string",
"null"
]
},
"object_contains": {
"type": [
"string",
"null"
],
"description": "Only return grains whose object field contains this substring (case-insensitive)."
},
"object_in": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Multi-value object filter (CAL `IN` operator). Union of matches."
},
"offset": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"preference_enrichment": {
"type": [
"boolean",
"null"
],
"description": "Enrich preference queries with co-occurring session grains."
},
"query": {
"type": [
"string",
"null"
]
},
"query_decompose": {
"type": [
"boolean",
"null"
],
"description": "ADR-023: Enable rule-based query decomposition (2-4 sub-queries per strategy + RRF)."
},
"query_expansion": {
"type": [
"boolean",
"null"
],
"description": "FR-A008 Phase 1: Enable rule-based query expansion (stemming + synonyms + RRF)."
},
"recency_weight": {
"type": [
"number",
"null"
],
"format": "double",
"description": "FR-A004: Per-query recency weight [0.0–1.0] for temporal freshness scoring."
},
"reference_date": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reference point for relative time annotations (epoch milliseconds). Defaults to now."
},
"relation": {
"type": [
"string",
"null"
]
},
"relation_in": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Multi-value relation filter (CAL `IN` operator). Union of matches."
},
"rerank": {
"type": [
"boolean",
"null"
],
"description": "Enable cross-encoder reranking (requires rerank feature + loaded model)."
},
"scope_path": {
"type": [
"string",
"null"
],
"description": "Scoped memory: hierarchical scope path (e.g., \"acme/prod/bot1\")."
},
"score_breakdown": {
"type": [
"boolean",
"null"
],
"description": "Include per-component score breakdown in results."
},
"session_affinity_boost": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Boost grains from the dominant namespace in the session [0.0–1.0]."
},
"session_census": {
"type": [
"boolean",
"null"
],
"description": "RF-3: Enable session-census retrieval for cross-session queries.\nQueries unrepresented sessions to recover grains missed by embedding clustering."
},
"session_census_max_queries": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "RF-3: Max follow-up queries (1-50, default 10).",
"minimum": 0
},
"session_census_min_per_session": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "RF-3: Min grains per unrepresented session (1-10, default 2).",
"minimum": 0
},
"session_census_min_score": {
"type": [
"number",
"null"
],
"format": "double",
"description": "RF-3: Min score for census grains (0.0-1.0, default 0.35)."
},
"subject": {
"type": [
"string",
"null"
]
},
"subject_affinity_boost": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Boost grains from the dominant subject in top-K results [0.0–1.0]."
},
"subject_contains": {
"type": [
"string",
"null"
],
"description": "Only return grains whose subject field contains this substring (case-insensitive)."
},
"subject_in": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Multi-value subject filter (CAL `IN` operator). Union of matches."
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Filter by structural tags."
},
"target_date": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Target date (epoch ms) for proximity-based scoring."
},
"target_date_weight": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Weight [0.0–1.0] for target_date proximity scoring."
},
"temporal_expr": {
"type": [
"string",
"null"
],
"description": "Natural-language temporal expression (e.g., \"last 7 days\", \"yesterday\")."
},
"temporal_field": {
"type": [
"string",
"null"
],
"description": "Temporal field to use for time range filtering: \"created_at\", \"event_date\", or \"both\"."
},
"time_range_end": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "End of time range filter (milliseconds since epoch)."
},
"time_range_start": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Start of time range filter (milliseconds since epoch)."
},
"user_id": {
"type": [
"string",
"null"
],
"description": "Filter by user_id."
}
},
"additionalProperties": false
},
"RecallChainAppRequest": {
"type": "object",
"description": "FR-A006: Multi-hop recall chain request.",
"required": [
"query"
],
"properties": {
"json": {
"type": [
"boolean",
"null"
],
"description": "Output as JSON (for debugging/explanation)."
},
"limit": {
"type": [
"integer",
"null"
],
"description": "Maximum total results after merge.",
"minimum": 0
},
"namespace": {
"type": [
"string",
"null"
],
"description": "Filter by namespace."
},
"query": {
"type": "string",
"description": "Complex question requiring multi-hop reasoning."
}
},
"additionalProperties": false
},
"RecallChainResponse": {
"type": "object",
"description": "FR-A006: Multi-hop recall chain response.",
"required": [
"sub_queries",
"reasoning",
"results",
"count"
],
"properties": {
"count": {
"type": "integer",
"description": "Total merged result count.",
"minimum": 0
},
"reasoning": {
"type": "string",
"description": "LLM reasoning about the decomposition."
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecallHitResponse"
},
"description": "Merged and deduplicated results."
},
"sub_queries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sub-queries derived from the original question."
}
}
},
"RecallHitResponse": {
"allOf": [
{
"$ref": "#/components/schemas/AppGrainResponse"
},
{
"type": "object",
"required": [
"score"
],
"properties": {
"conflict_status": {
"type": [
"string",
"null"
],
"description": "Conflict status: \"current\" or \"outdated\" (when conflict_resolution is active)."
},
"explanation": {
"type": [
"string",
"null"
],
"description": "Human-readable explanation (when explain=true in request)."
},
"recall_source": {
"type": [
"string",
"null"
],
"description": "Origin of this result in the recall pipeline: \"primary\", \"expansion\", or \"census\"."
},
"relative_time": {
"type": [
"string",
"null"
],
"description": "Human-readable relative time label (when annotate_relative_time=true)."
},
"score": {
"type": "number",
"format": "double",
"description": "Final combined score [0.0–1.0]."
},
"score_breakdown": {
"type": [
"object",
"null"
],
"description": "Per-component score breakdown (when score_breakdown=true in request)."
},
"supersession_status": {
"type": [
"string",
"null"
],
"description": "Supersession status: \"current\" or \"superseded\" (when RF-2 scoring applied)."
}
}
}
],
"description": "Recall-specific response with score information (FR-A010)."
},
"RecallRequest": {
"type": "object",
"description": "Request body for recall queries.",
"properties": {
"confidence_threshold": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Minimum confidence threshold"
},
"embedding": {
"type": [
"array",
"null"
],
"items": {
"type": "number",
"format": "float"
},
"description": "Pre-computed embedding vector for KNN semantic search"
},
"grain_type": {
"type": [
"string",
"null"
],
"description": "Filter by grain type"
},
"limit": {
"type": [
"integer",
"null"
],
"description": "Maximum results",
"minimum": 0
},
"namespace": {
"type": [
"string",
"null"
],
"description": "Filter by namespace"
},
"object": {
"type": [
"string",
"null"
],
"description": "Structured: match object"
},
"query": {
"type": [
"string",
"null"
],
"description": "Free-text query string (BM25 search)"
},
"relation": {
"type": [
"string",
"null"
],
"description": "Structured: match relation/predicate"
},
"subject": {
"type": [
"string",
"null"
],
"description": "Structured: match subject"
},
"time_end": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Time range end (epoch ms)"
},
"time_start": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Time range start (epoch ms)"
},
"user_id": {
"type": [
"string",
"null"
],
"description": "Filter by user_id"
}
}
},
"RecallResponse": {
"type": "object",
"description": "Recall response with scored results.",
"required": [
"results",
"count",
"total",
"has_more"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"entities": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "List of distinct entity subjects. Populated when count_entities=true."
},
"entity_count": {
"type": [
"integer",
"null"
],
"description": "Number of distinct entities (subjects) in results. Populated when count_entities=true.",
"minimum": 0
},
"entity_coverage": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Entity coverage score [0.0–1.0]: matched query tokens / total tokens."
},
"exhaustive_metadata": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ExhaustiveMetadata",
"description": "WI-EXHAUST: Exhaustive recall execution metadata."
}
]
},
"has_more": {
"type": "boolean",
"description": "True when more results may exist beyond this page."
},
"low_coverage_warning": {
"type": "boolean",
"description": "True when results are sparse and query has multiple key tokens."
},
"offset": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecallHitResponse"
}
},
"session_census_metadata": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SessionCensusMetadata",
"description": "RF-3: Session-census retrieval metadata."
}
]
},
"session_coverage_ratio": {
"type": [
"number",
"null"
],
"format": "double",
"description": "RF-6: Ratio of sessions with grains in results vs total sessions [0.0–1.0]."
},
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecallHitResponse"
},
"description": "Source grains for results that have `derived_from` links.\nPopulated when `include_sources=true` in the request."
},
"supersede_chain_complete": {
"type": [
"boolean",
"null"
],
"description": "RF-6: Whether all supersession chains in the result set are fully resolved."
},
"topic_coverage": {
"type": [
"string",
"null"
],
"description": "Topic coverage of query tokens in result grains."
},
"total": {
"type": "integer",
"minimum": 0
},
"total_candidates": {
"type": [
"integer",
"null"
],
"description": "Total candidates before filtering to limit.",
"minimum": 0
}
}
},
"RegionInfo": {
"type": "object",
"description": "Region metadata returned in /api/config for cloud console region switching.",
"required": [
"id",
"name",
"provider",
"api_base"
],
"properties": {
"api_base": {
"type": "string",
"description": "API base URL for this region (e.g., \"https://dub.areev.ai\")."
},
"current": {
"type": "boolean",
"description": "Whether this is the current node's region."
},
"id": {
"type": "string",
"description": "Region identifier (e.g., \"eu\", \"us\", \"ap\")."
},
"name": {
"type": "string",
"description": "Display name (e.g., \"Europe (Ireland)\")."
},
"provider": {
"type": "string",
"description": "Cloud provider (e.g., \"azure\", \"aws\", \"gcp\")."
}
}
},
"RegisterAgentIdentityRequest": {
"type": "object",
"description": "Request body for POST /memories/{id}/agents/identities.",
"required": [
"agent_id"
],
"properties": {
"agent_id": {
"type": "string",
"description": "Unique agent identifier (required)."
},
"capabilities": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "List of agent capabilities."
},
"name": {
"type": [
"string",
"null"
],
"description": "Human-readable agent name."
},
"version": {
"type": [
"string",
"null"
],
"description": "Agent software version."
}
}
},
"RejectResponse": {
"type": "object",
"description": "Response body for `POST .../proposals/{p_id}/reject`.",
"required": [
"proposal_id",
"status"
],
"properties": {
"proposal_id": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"RenameThreadRequest": {
"type": "object",
"description": "Request body for renaming a thread.",
"required": [
"title"
],
"properties": {
"title": {
"type": "string"
}
}
},
"RestrictionRequest": {
"type": "object",
"description": "Request body for processing restriction.",
"required": [
"user_id"
],
"properties": {
"reason": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "string"
}
}
},
"RetentionNamespaceStatus": {
"type": "object",
"description": "Retention status for a single namespace.",
"required": [
"namespace",
"policy",
"retention_period",
"total_grains",
"expired",
"expiring_soon",
"status"
],
"properties": {
"expired": {
"type": "integer",
"minimum": 0
},
"expiring_soon": {
"type": "integer",
"minimum": 0
},
"namespace": {
"type": "string"
},
"policy": {
"type": "string"
},
"retention_period": {
"type": "string"
},
"status": {
"type": "string",
"description": "Status: \"compliant\", \"action_required\", or \"expiring_soon\"."
},
"total_grains": {
"type": "integer",
"minimum": 0
}
}
},
"RetentionStatusResponse": {
"type": "object",
"description": "Overall retention status response.",
"required": [
"total_grains",
"expired",
"expiring_soon",
"namespaces",
"config_required"
],
"properties": {
"config_hint": {
"type": [
"string",
"null"
]
},
"config_required": {
"type": "boolean"
},
"expired": {
"type": "integer",
"minimum": 0
},
"expiring_soon": {
"type": "integer",
"minimum": 0
},
"last_enforcement": {
"type": [
"string",
"null"
]
},
"namespaces": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RetentionNamespaceStatus"
}
},
"total_grains": {
"type": "integer",
"minimum": 0
}
}
},
"RotateCallbackSecretResponse": {
"type": "object",
"required": [
"secret",
"key_fingerprint"
],
"properties": {
"key_fingerprint": {
"type": "string",
"description": "First 16 hex chars of `sha256(secret)`. Use as the `If-Match`\nheader on the next rotation to prove possession of this secret."
},
"secret": {
"type": "string",
"description": "New base64url-no-pad HMAC secret. Surfaced exactly once in this\nresponse body and never afterwards — capture it now or rotate\nagain. No GET/LIST handler will ever return it."
}
}
},
"ScopeEraseRequest": {
"type": "object",
"required": [
"scope_path"
],
"properties": {
"scope_path": {
"type": "string"
}
}
},
"ScopeErasureProofResponse": {
"type": "object",
"description": "Scope erasure proof response (differs from user erasure).",
"required": [
"status",
"scope_path",
"grains_deleted",
"key_fingerprint",
"timestamp"
],
"properties": {
"grains_deleted": {
"type": "integer",
"format": "int64",
"description": "Number of grains deleted.",
"minimum": 0
},
"key_fingerprint": {
"type": "string",
"description": "Fingerprint of the encryption key used for erasure."
},
"scope_path": {
"type": "string",
"description": "The scope path that was erased."
},
"status": {
"type": "string",
"description": "Erasure status: \"ok\" or \"not_found\"."
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "Timestamp of the erasure (epoch milliseconds)."
}
}
},
"ScopeLevelDef": {
"type": "object",
"description": "Definition of a single level in the scope hierarchy.",
"required": [
"depth",
"label"
],
"properties": {
"default_precedence": {
"$ref": "#/components/schemas/Precedence",
"description": "Default precedence when no grain-type-specific rule exists."
},
"depth": {
"type": "integer",
"format": "int32",
"description": "Depth index (0 = root, 1 = first child level, etc.).",
"minimum": 0
},
"label": {
"type": "string",
"description": "Human-readable label for this level (e.g., \"organization\", \"workspace\")."
},
"precedence_rules": {
"type": "object",
"description": "Per-grain-type precedence overrides. Key is grain type name (e.g., \"fact\").",
"additionalProperties": {
"$ref": "#/components/schemas/Precedence"
},
"propertyNames": {
"type": "string"
}
},
"sibling_read": {
"type": "boolean",
"description": "Whether entities at this depth can read siblings (other children of the same parent)."
},
"write_policy": {
"$ref": "#/components/schemas/WritePolicy",
"description": "Write access policy for this level."
}
}
},
"ScopeTree": {
"type": "object",
"description": "A scope tree configuration defining the hierarchy shape and rules.",
"required": [
"levels"
],
"properties": {
"created_at_ms": {
"type": "integer",
"format": "int64",
"description": "Timestamp when this configuration was created (epoch milliseconds).\nDefaults to current time if not provided."
},
"id": {
"type": "string",
"description": "Unique identifier for this scope tree configuration.\nAuto-generated (UUID) if not provided."
},
"levels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ScopeLevelDef"
},
"description": "Ordered list of level definitions (index 0 = root)."
}
}
},
"SecurityInfo": {
"type": "object",
"required": [
"sso_configured"
],
"properties": {
"sso_configured": {
"type": "boolean"
},
"sso_provider": {
"type": [
"string",
"null"
]
},
"sso_status": {
"type": [
"string",
"null"
]
}
}
},
"ServerInfo": {
"type": "object",
"required": [
"version",
"auth_mode",
"distributed",
"memories_count"
],
"properties": {
"auth_mode": {
"type": "string"
},
"distributed": {
"type": "boolean"
},
"memories_count": {
"type": "integer",
"minimum": 0
},
"version": {
"type": "string"
}
}
},
"SessionBootstrapQuery": {
"type": "object",
"description": "Session bootstrap query params.",
"properties": {
"recent_tools_limit": {
"type": [
"integer",
"null"
],
"description": "Maximum number of recent actions to include (default: 20).",
"minimum": 0
}
}
},
"SessionCensusMetadata": {
"type": "object",
"description": "Metadata about session-census execution, returned in RecallResult.\n\nProvides observability into the census process: how many sessions\nexist, how many were already represented, how many were queried,\nand how many grains each census query contributed.",
"required": [
"total_sessions",
"represented_sessions",
"census_queries_issued",
"grains_added",
"session_stats"
],
"properties": {
"census_queries_issued": {
"type": "integer",
"description": "Sessions queried by census (min of unrepresented, max_additional_queries).",
"minimum": 0
},
"grains_added": {
"type": "integer",
"description": "Total new grains added from census queries (after dedup + min_score filter).",
"minimum": 0
},
"represented_sessions": {
"type": "integer",
"description": "Sessions already represented in the initial recall results.",
"minimum": 0
},
"session_stats": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CensusSessionStat"
},
"description": "Per-session census stats."
},
"total_sessions": {
"type": "integer",
"description": "Total sessions (namespaces) discovered for this user.",
"minimum": 0
}
}
},
"SessionFailedToolsQuery": {
"type": "object",
"description": "Session failed actions query params.",
"properties": {
"since": {
"type": [
"integer",
"null"
],
"format": "int64"
}
}
},
"SessionGoalsQuery": {
"type": "object",
"description": "Session active goals query params (currently no filters -- active_goals always returns active state)."
},
"SessionToolsQuery": {
"type": "object",
"description": "Session recent actions query params.",
"properties": {
"limit": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
},
"SettingsResponse": {
"type": "object",
"required": [
"server",
"security"
],
"properties": {
"security": {
"$ref": "#/components/schemas/SecurityInfo"
},
"server": {
"$ref": "#/components/schemas/ServerInfo"
}
}
},
"SourceCounts": {
"type": "object",
"description": "Count of alerts from each source.",
"required": [
"compliance",
"contradictions",
"enforcement",
"retention",
"metrics"
],
"properties": {
"compliance": {
"type": "integer",
"minimum": 0
},
"contradictions": {
"type": "integer",
"minimum": 0
},
"enforcement": {
"type": "integer",
"minimum": 0
},
"knowledge_sources": {
"type": "integer",
"description": "Knowledge Sources with one or more pending change proposals\n(source #6, v1+). Each KS contributes at most one alert (proposals\non the same KS collapse into a single card with aggregate counts).\nField is additive — older clients ignore unknown keys.",
"minimum": 0
},
"metrics": {
"type": "integer",
"minimum": 0
},
"retention": {
"type": "integer",
"minimum": 0
}
}
},
"StatsHistoryQuery": {
"type": "object",
"description": "Stats history query params.",
"properties": {
"days": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
},
"StatsHistoryResponse": {
"type": "object",
"description": "Stats history response.",
"required": [
"snapshots",
"days"
],
"properties": {
"days": {
"type": "integer",
"minimum": 0
},
"snapshots": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsSnapshot"
}
}
}
},
"StatsResponse": {
"type": "object",
"description": "Database statistics.",
"required": [
"total_grains",
"disk_space_bytes"
],
"properties": {
"disk_space_bytes": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"total_grains": {
"type": "integer",
"minimum": 0
}
}
},
"StatsSnapshot": {
"type": "object",
"description": "Stats history snapshot.",
"required": [
"total_grains",
"knowledge_density"
],
"properties": {
"knowledge_density": {
"type": "number",
"format": "double"
},
"total_grains": {
"type": "integer",
"minimum": 0
}
}
},
"StatusOkResponse": {
"type": "object",
"description": "Generic status response for simple OK/deleted/cancelled operations.",
"required": [
"status"
],
"properties": {
"status": {
"type": "string"
}
}
},
"SupersedeAppRequest": {
"type": "object",
"description": "Supersede request body (App format).",
"required": [
"blob_hash"
],
"properties": {
"blob_hash": {
"type": "string"
},
"confidence": {
"type": [
"number",
"null"
],
"format": "double"
},
"fields": {
"type": [
"object",
"null"
],
"description": "Generic field overrides (for any grain type).",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
},
"namespace": {
"type": [
"string",
"null"
]
},
"object": {
"type": [
"string",
"null"
]
},
"relation": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"tags": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
}
}
},
"SupersedeAppResponse": {
"type": "object",
"description": "Supersede response (App format).",
"required": [
"blob_hash",
"superseded",
"status"
],
"properties": {
"blob_hash": {
"type": "string"
},
"status": {
"type": "string"
},
"superseded": {
"type": "string"
}
}
},
"SupersedeReason": {
"type": "string",
"description": "Why a `Supersede` action was generated. Surfaces in the proposal-review\nmodal so the user understands what changed without diffing grains\nmanually.",
"enum": [
"content_changed",
"renamed",
"moved"
]
},
"SyncPolicy": {
"type": "object",
"description": "How the KS stays in sync.",
"properties": {
"auto_sync": {
"type": "boolean",
"description": "User opt-in. When true, the cell registers a polling trigger with\naxtion so upstream edits surface as change-proposal alerts. Default\nfalse — users must explicitly opt in via the Add-content modal."
},
"poll_seconds": {
"type": "integer",
"format": "int32",
"description": "Polling cadence in seconds when auto_sync is on. 60s is well under\nDrive's quota (changes.list with pageToken is ~50ms / 200B) and\nfeels real-time. v2 push notifications make this a fallback.",
"minimum": 0
},
"prefer_listener": {
"type": "boolean",
"description": "Prefer webhook (listener) over polling when the connector exposes one.\nv2+ enables Drive `files.watch`, Notion webhooks, etc."
}
}
},
"SyncResponse": {
"type": "object",
"description": "Response body for sync-trigger.",
"required": [
"ks_id",
"status",
"queued_files",
"message"
],
"properties": {
"ks_id": {
"type": "string"
},
"message": {
"type": "string"
},
"queued_files": {
"type": "integer",
"minimum": 0
},
"status": {
"type": "string"
}
}
},
"TeamMemberResponse": {
"type": "object",
"required": [
"key_id",
"principal",
"key_prefix",
"scopes",
"active",
"created_at"
],
"properties": {
"active": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
]
},
"key_id": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"principal": {
"type": "string"
},
"role": {
"type": [
"string",
"null"
]
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"TeamResponse": {
"type": "object",
"required": [
"auth_mode",
"members"
],
"properties": {
"auth_mode": {
"type": "string"
},
"members": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMemberResponse"
}
}
}
},
"ToolAnnotations": {
"type": "object",
"description": "MCP-compatible tool annotations describing side-effect properties.\n\nAll flags default to `false`. The combination\n`read_only && destructive` is rejected at write time\n(`SchemaSubsetError` / `MEM-E103`) — a tool cannot be both read-only\nand destructive.",
"properties": {
"destructive": {
"type": "boolean"
},
"idempotent": {
"type": "boolean"
},
"read_only": {
"type": "boolean"
}
}
},
"ToolCallTrace": {
"type": "object",
"required": [
"iteration",
"tool_id",
"arguments",
"result",
"is_error"
],
"properties": {
"arguments": {
"type": "string",
"description": "Arguments the LLM sent (raw JSON string from the provider)."
},
"is_error": {
"type": "boolean"
},
"iteration": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"result": {
"type": "string",
"description": "Result text the tool returned (or error message)."
},
"tool_id": {
"type": "string"
}
}
},
"ToolResultCallback": {
"type": "object",
"required": [
"memory_id",
"harness_slug",
"correlation_id",
"principal",
"outcome"
],
"properties": {
"content": {
"type": "string"
},
"correlation_id": {
"type": "string"
},
"harness_slug": {
"type": "string"
},
"is_error": {
"type": "boolean"
},
"memory_id": {
"type": "string"
},
"outcome": {
"$ref": "#/components/schemas/ToolResultOutcome"
},
"principal": {
"type": "string"
}
}
},
"ToolResultOutcome": {
"type": "string",
"enum": [
"completed",
"failed"
]
},
"TreeStatsResponse": {
"type": "object",
"description": "Structured import statistics returned when `structured = true`.",
"required": [
"section_count",
"entity_count",
"gt_link_count",
"max_depth",
"document_grain_hash"
],
"properties": {
"document_grain_hash": {
"type": "string"
},
"entity_count": {
"type": "integer",
"minimum": 0
},
"gt_link_count": {
"type": "integer",
"minimum": 0
},
"max_depth": {
"type": "integer",
"minimum": 0
},
"section_count": {
"type": "integer",
"minimum": 0
}
}
},
"UnwrapWorkspaceDekRequest": {
"type": "object",
"description": "Request body for `POST /api/crypto/workspace-dek/unwrap`.",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "string"
}
}
},
"UnwrapWorkspaceDekResponse": {
"type": "object",
"description": "Response for `POST /api/crypto/workspace-dek/unwrap` (200 OK).\n\nManual `Debug` impl redacts the `dek` field for safe logging.",
"required": [
"dek",
"keyVersion",
"wrappedAt"
],
"properties": {
"dek": {
"type": "string"
},
"keyVersion": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"wrappedAt": {
"type": "string"
}
}
},
"UpdateGoalStateRequest": {
"type": "object",
"description": "Request body for updating a goal state.",
"required": [
"state"
],
"properties": {
"reason": {
"type": [
"string",
"null"
]
},
"state": {
"type": "string",
"description": "Target state. Valid values: \"active\", \"satisfied\", \"failed\", \"suspended\".",
"example": "satisfied"
}
}
},
"UpdateHookRequest": {
"type": "object",
"description": "Request body for updating a hook.",
"properties": {
"acknowledge_pii_risk": {
"type": [
"boolean",
"null"
]
},
"event_filters": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"name": {
"type": [
"string",
"null"
]
},
"redaction_mode": {
"type": [
"string",
"null"
]
},
"rotate_secret": {
"type": "boolean",
"description": "If true, rotates the HMAC signing secret and returns the new secret once."
},
"status": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
]
}
}
},
"UpdateKsRequest": {
"type": "object",
"description": "Request body for `PUT /knowledge-sources/{ks_id}` (rename + scope edit).",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"scope": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/KsScope"
}
]
},
"sync_policy": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SyncPolicy"
}
]
}
}
},
"UpdateLlmSettingsRequest": {
"type": "object",
"description": "Request body for PUT /api/settings/llm.\n`api_key: null` (or absent) means \"keep the existing key\".",
"required": [
"provider",
"model"
],
"properties": {
"api_key": {
"type": [
"string",
"null"
]
},
"base_url": {
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
"provider": {
"type": "string"
}
}
},
"UpdateModelAssignmentsRequest": {
"type": "object",
"description": "PUT /api/settings/model-assignments request body.",
"properties": {
"chat": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
},
"embed": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
},
"import": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
},
"rerank": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ModelRef"
}
]
}
}
},
"UpdatePreferencesRequest": {
"type": "object",
"description": "PUT /api/preferences request body — set/update multiple preferences.",
"required": [
"preferences"
],
"properties": {
"preferences": {
"type": "object",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
}
}
},
"UpdateSsoRequest": {
"type": "object",
"required": [
"provider",
"metadata_url",
"entity_id"
],
"properties": {
"allowed_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"audience": {
"type": [
"string",
"null"
]
},
"entity_id": {
"type": "string"
},
"metadata_url": {
"type": "string"
},
"principal_claim": {
"type": [
"string",
"null"
]
},
"provider": {
"type": "string"
}
}
},
"UpdateTeamMemberRequest": {
"type": "object",
"properties": {
"display_name": {
"type": [
"string",
"null"
]
},
"role": {
"type": [
"string",
"null"
]
}
}
},
"UpsertProviderRequest": {
"type": "object",
"description": "Unified PUT request — the handler distinguishes catalog vs custom by checking if\nthe ID is a catalog entry.",
"properties": {
"api_key": {
"type": [
"string",
"null"
]
},
"auth_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AuthType"
}
]
},
"base_url": {
"type": [
"string",
"null"
]
},
"base_url_override": {
"type": [
"string",
"null"
]
},
"display_name": {
"type": [
"string",
"null"
]
},
"enabled": {
"type": [
"boolean",
"null"
]
},
"models": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/CustomModel"
}
},
"provider_type": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ProviderType"
}
]
}
}
},
"VerificationCheckResponse": {
"type": "object",
"description": "Verification check result (App format).",
"required": [
"check_id",
"status",
"passed",
"message",
"evidence"
],
"properties": {
"check_id": {
"type": "string"
},
"evidence": {
"type": "object"
},
"lock_reason": {
"type": [
"string",
"null"
],
"description": "Populated only when `status == \"locked\"`. Distinguishes\n`\"tier_run_cost\"` (compute-budget lock) from\n`\"tier_remediation_feature\"` (regulation attestation that requires\nScale features to remediate). Surfaces to the UI as the\n\"Upgrade to run\" vs \"Upgrade to remediate\" sub-label."
},
"message": {
"type": "string"
},
"passed": {
"type": "boolean"
},
"status": {
"type": "string"
}
}
},
"VerificationLatestResponse": {
"type": "object",
"description": "Verification latest response.\n\nCarries the same tier-aware counters as `VerificationRunResponse` so a\nbrowser reload after `verify/run` preserves the honest-disclosure header\nwithout requiring the user to re-click \"Run Verification\".",
"required": [
"results"
],
"properties": {
"message": {
"type": [
"string",
"null"
]
},
"metadata": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/VerifyRunMetadata"
}
]
},
"results": {
"type": "array",
"items": {
"type": "object"
}
},
"tier_hint": {
"type": [
"string",
"null"
],
"description": "Caller tier at the cached run (\"free\" | \"paid\")."
},
"total_checks": {
"type": [
"integer",
"null"
],
"description": "Total registered checks in the response (`total_evaluated + total_locked`).",
"minimum": 0
},
"total_evaluated": {
"type": [
"integer",
"null"
],
"description": "Checks that actually ran (passed + failed + warned + skipped).",
"minimum": 0
},
"total_locked": {
"type": [
"integer",
"null"
],
"description": "Checks emitted as `Locked` stubs.",
"minimum": 0
}
}
},
"VerificationRunResponse": {
"type": "object",
"description": "Verification run response.\n\nCounter fields follow the compliance-reviewer's honest-disclosure\ncontract (see `docs/work/areev-compliance/*`):\n\n- `passed / failed / warned / skipped` — per-status counts of checks\n that actually executed their check function.\n- `total_evaluated` — sum of the four above. Checks that ran.\n- `total_locked` — count of `\"locked\"`-status stubs emitted without\n executing their check function (Free tier, non-allow-list,\n non-force-run).\n- `total_checks` — `total_evaluated + total_locked`. The *honest*\n denominator for a compliance score: `passed / total_checks`.\n\nThe UI MUST NOT render `passed / total_evaluated` without also\nprominently showing `total_locked` in the same card. Rendering\n\"18/18 passed\" when 42 checks are locked is a misleading disclosure\nunder GDPR Art. 5(2) accountability framing.\n\n`tier_hint` records the caller tier at run time — `\"free\"` or\n`\"paid\"`. Free responses intermix Locked stubs with executed results;\nPaid responses never contain Locked stubs (apart from always-Locked\nclassifications, which are not applicable on Paid).",
"required": [
"results",
"total",
"passed",
"failed"
],
"properties": {
"failed": {
"type": "integer",
"minimum": 0
},
"metadata": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/VerifyRunMetadata"
}
]
},
"passed": {
"type": "integer",
"minimum": 0
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VerificationCheckResponse"
}
},
"skipped": {
"type": "integer",
"description": "Checks with `status == \"skip\"`.",
"minimum": 0
},
"tier_hint": {
"type": "string",
"description": "Caller tier at run time: `\"free\"` or `\"paid\"`."
},
"total": {
"type": "integer",
"minimum": 0
},
"total_checks": {
"type": "integer",
"description": "Total registered checks in the response (`total_evaluated + total_locked`).\nThe *honest* denominator for a compliance score.",
"minimum": 0
},
"total_evaluated": {
"type": "integer",
"description": "Checks that actually ran (`passed + failed + warned + skipped`).",
"minimum": 0
},
"total_locked": {
"type": "integer",
"description": "Checks emitted as `Locked` stubs (did not execute their check fn).",
"minimum": 0
},
"warned": {
"type": "integer",
"description": "Checks with `status == \"warn\"`.",
"minimum": 0
}
}
},
"VerifyRunMetadata": {
"type": "object",
"description": "Metadata about a verification run.",
"required": [
"run_at",
"duration_ms",
"regulations_checked",
"regulation_names"
],
"properties": {
"duration_ms": {
"type": "integer",
"format": "int64",
"description": "Duration of the run in milliseconds.",
"minimum": 0
},
"regulation_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of regulations checked."
},
"regulations_checked": {
"type": "integer",
"description": "Number of unique regulations checked.",
"minimum": 0
},
"run_at": {
"type": "string",
"description": "ISO 8601 timestamp of when the run started."
}
}
},
"VerifyRunRequest": {
"type": "object",
"description": "Verify run request body.",
"properties": {
"regulation": {
"type": [
"string",
"null"
]
},
"sample_size": {
"type": [
"integer",
"null"
],
"minimum": 0
}
}
},
"WritePolicy": {
"type": "string",
"description": "Controls who can write to a scope level.",
"enum": [
"admin_only",
"self_only",
"inherited"
]
}
},
"securitySchemes": {
"api_key": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API Key (ar_*)",
"description": "API key passed as Bearer token. Set AREEV_SYSTEM_KEY on the server."
},
"bearer": {
"type": "http",
"scheme": "bearer",
"description": "JWT bearer token (requires --auth oidc or --auth composite)."
}
}
},
"security": [
{
"api_key": []
}
],
"tags": [
{
"name": "health",
"description": "Health check"
},
{
"name": "memories",
"description": "Memory management"
},
{
"name": "grains",
"description": "Grain CRUD — add, recall, forget, supersede"
},
{
"name": "pull-stats",
"description": "Per-grain pull telemetry (issue #536)"
},
{
"name": "stats",
"description": "Memory statistics and history"
},
{
"name": "agents",
"description": "Agent registry"
},
{
"name": "compliance",
"description": "Verification, audit trail, export, PII detection"
},
{
"name": "policy",
"description": "Policy configuration and simulation"
},
{
"name": "authz",
"description": "Zanzibar-style authorization"
},
{
"name": "import",
"description": "Document import pipeline"
},
{
"name": "graph",
"description": "Memory graph traversal"
},
{
"name": "sessions",
"description": "Session-scoped queries and agent harness"
},
{
"name": "goals",
"description": "Goal orchestration"
},
{
"name": "intelligence",
"description": "Consolidation, context compilation, events"
},
{
"name": "provenance",
"description": "Decision provenance (EU AI Act Art. 86)"
},
{
"name": "scoped",
"description": "Hierarchical scoped memory"
},
{
"name": "agent-identity",
"description": "Agent identity management"
},
{
"name": "llm",
"description": "LLM chat proxy and settings"
},
{
"name": "preferences",
"description": "Per-user preferences"
},
{
"name": "providers",
"description": "LLM provider registry and model discovery"
},
{
"name": "import-export",
"description": "Bulk import/export (.mg format)"
},
{
"name": "auth",
"description": "API key management"
},
{
"name": "admin",
"description": "Settings and team management"
},
{
"name": "chat",
"description": "Conversational memory engine"
},
{
"name": "alerts",
"description": "Aggregated attention alerts"
},
{
"name": "admin",
"description": "Memory-scoped admin operations (registry reload, etc.)"
},
{
"name": "onboarding",
"description": "KYC onboarding (cloud-only)"
},
{
"name": "crypto",
"description": "Workspace DEK management for envelope encryption"
}
]
}