{ "openapi": "3.1.0", "info": { "title": "Memra API", "version": "4.6.1", "description": "Memory API for AI agents and LLM applications. Persistent, searchable memory for any AI agent through a clean REST API." }, "servers": [ { "url": "https:\/\/usememra.com\/api\/v1" } ], "security": [ { "http": [] } ], "paths": { "\/audit-log": { "get": { "operationId": "auditLog.index", "summary": "Query audit log entries with filters and pagination", "tags": [ "AuditLog" ], "parameters": [ { "name": "tenant_id", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "project_id", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "memory_id", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "operation", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "create", "read", "update", "delete", "recall", "batch", "supersede", "health_check", "refresh", "erasure_request", "bulk_delete", "list" ] } }, { "name": "date_from", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "date_to", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "memory_id": { "type": [ "string", "null" ] }, "operation": { "type": [ "string", "null" ] }, "actor": { "type": "string" }, "ip_address": { "type": [ "string", "null" ] }, "tenant_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "details": { "type": [ "array", "null" ], "items": {} }, "created_at": { "type": "string" } }, "required": [ "id", "memory_id", "operation", "actor", "ip_address", "tenant_id", "project_id", "details", "created_at" ] } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "limit": { "type": [ "object", "null" ] }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "has_more" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/audit-log\/export": { "get": { "operationId": "auditLog.export", "description": "Rate limited to 1 per day per account via throttle:export middleware\n(separate bucket per export endpoint).", "summary": "Export audit log entries as JSON or CSV attachment", "tags": [ "AuditLog" ], "parameters": [ { "name": "tenant_id", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "project_id", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "memory_id", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "operation", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "create", "read", "update", "delete", "recall", "batch", "supersede", "health_check", "refresh", "erasure_request", "bulk_delete", "list" ] } }, { "name": "date_from", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "date_to", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "format", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "csv", "json" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "text\/csv; charset=UTF-8": { "schema": { "type": "string" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/agents\/{agent_id}\/bootstrap": { "get": { "operationId": "bootstrap.bootstrap", "description": "Returns priority-ordered memories with token budgeting for agent session initialization.\nUses 5-tier priority ordering: decisions, high-importance facts, recent context,\nmost-accessed patterns, and health warnings.", "summary": "Get bootstrap context for an agent", "tags": [ "Bootstrap" ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 } }, { "name": "max_tokens", "in": "query", "schema": { "type": "integer", "minimum": 100, "maximum": 4000 } }, { "name": "include_types[]", "in": "query", "schema": { "type": "array", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ], "items": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } } }, { "name": "exclude_types[]", "in": "query", "schema": { "type": "array", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ], "items": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } } }, { "name": "recency_days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365 } }, { "name": "since_revision", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "planner", "generator", "evaluator", "default" ] } }, { "name": "namespace_recursive", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "agent_id": { "type": "string" }, "tenant_id": {}, "project_id": {}, "memories": {}, "token_estimate": {}, "health_warnings": {}, "revision": { "anyOf": [ {}, { "type": "integer", "enum": [ 0 ] } ] }, "generated_at": { "type": "string" }, "cache_ttl": { "type": "integer" }, "cached": { "type": "string" }, "delta": { "type": "boolean" }, "tombstones": { "anyOf": [ {}, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "agent_id", "tenant_id", "project_id", "memories", "token_estimate", "health_warnings", "revision", "generated_at", "cache_ttl", "cached", "delta", "tombstones" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "forbidden" }, "message": { "type": "string", "const": "Agent ID does not match authenticated API key" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/agents\/{agent_id}\/bootstrap\/configure": { "post": { "operationId": "bootstrap.configure", "description": "Stores preferences in Redis (persisted indefinitely) so subsequent\nbootstrap calls use these defaults unless overridden by query params.", "summary": "Save bootstrap preferences for an agent", "tags": [ "Bootstrap" ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ConfigureBootstrapRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "agent_id": { "type": "string" }, "message": { "type": "string", "const": "Bootstrap preferences saved" }, "config": { "anyOf": [ { "type": "object", "properties": { "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 500 ] } ] }, "include_types": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "exclude_types": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "recency_days": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 7 ] } ] }, "role_config": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "max_tokens", "include_types", "exclude_types", "recency_days", "role_config" ] }, { "type": "object", "properties": { "max_tokens": { "type": "integer", "const": 500 }, "include_types": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "exclude_types": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "recency_days": { "type": "integer", "const": 7 }, "role_config": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "max_tokens", "include_types", "exclude_types", "recency_days", "role_config" ] } ] } }, "required": [ "agent_id", "message", "config" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "forbidden" }, "message": { "type": "string", "const": "Agent ID does not match authenticated API key" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "bootstrap.showConfig", "description": "Returns the saved preferences or defaults if none have been configured.", "summary": "Get current bootstrap preferences for an agent", "tags": [ "Bootstrap" ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "agent_id": { "type": "string" }, "config": { "anyOf": [ { "type": "object", "properties": { "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 500 ] } ] }, "include_types": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "exclude_types": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "recency_days": { "anyOf": [ { "type": "integer" }, { "type": "integer", "enum": [ 7 ] } ] }, "role_config": { "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "max_tokens", "include_types", "exclude_types", "recency_days", "role_config" ] }, { "type": "object", "properties": { "max_tokens": { "type": "integer", "const": 500 }, "include_types": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "exclude_types": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "recency_days": { "type": "integer", "const": 7 }, "role_config": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "max_tokens", "include_types", "exclude_types", "recency_days", "role_config" ] } ] } }, "required": [ "agent_id", "config" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "forbidden" }, "message": { "type": "string", "const": "Agent ID does not match authenticated API key" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/entities": { "get": { "operationId": "entity.index", "description": "Distinct entities for a namespace with memory counts, most-mentioned\nfirst. PII entities appear under their stable IDs (never raw values).", "summary": "List entities", "tags": [ "Entities", "Entity" ], "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 50 } }, { "name": "entity_type", "in": "query", "schema": { "type": "string", "maxLength": 50 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "is_pii": { "type": "boolean" }, "memory_count": { "type": "integer" } }, "required": [ "name", "type", "is_pii", "memory_count" ] } } }, "required": [ "entities" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/entities\/{name}\/memories": { "get": { "operationId": "entity.memories", "description": "Metadata only (no content) \u2014 fetch full content via GET \/memories\/{id}.", "summary": "List memories mentioning an entity", "tags": [ "Entities", "Entity" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 50 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "memories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "integer" }, "tags": { "anyOf": [ { "type": "array", "items": {} }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "tenant_id": { "type": "string" }, "project_id": { "type": "string" }, "trust_state": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "proposed" ] } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "importance", "tags", "tenant_id", "project_id", "trust_state", "created_at", "updated_at" ] } }, "returned": { "type": "string" }, "total": { "type": "string", "description": "Total edges for this entity, not the page size (ADV-8)" } }, "required": [ "entity", "memories", "returned", "total" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/memories\/{id}\/erasure-request": { "post": { "operationId": "erasureRequest.store", "description": "Schedules the memory for deletion 30 days from now per applicable data protection law.\nThe daily ProcessErasureRequests command processes due requests.", "summary": "Create an erasure request for a memory", "tags": [ "ErasureRequest" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "request_id": { "type": "string" }, "memory_id": { "type": "string" }, "status": { "type": "string", "const": "pending" }, "requested_at": { "type": "string" }, "scheduled_deletion_date": { "type": "string" }, "message": { "type": "string", "const": "Memory scheduled for deletion. Deletion will be processed on or after the scheduled date." } }, "required": [ "request_id", "memory_id", "status", "requested_at", "scheduled_deletion_date", "message" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "erasure_request_exists" }, "message": { "type": "string", "const": "A pending erasure request already exists for this memory." }, "existing_request": { "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "type": "string" }, "scheduled_deletion_date": { "type": "string" } }, "required": [ "request_id", "status", "scheduled_deletion_date" ] } }, "required": [ "code", "message", "existing_request" ] } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "erasureRequest.show", "summary": "Show the latest erasure request for a memory", "tags": [ "ErasureRequest" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "request_id": { "type": "string" }, "memory_id": { "type": "string" }, "status": { "type": "string" }, "requested_at": { "type": "string" }, "scheduled_deletion_date": { "type": "string" }, "completed_at": { "type": "string" }, "details": { "type": "string" } }, "required": [ "request_id", "memory_id", "status", "requested_at", "scheduled_deletion_date", "completed_at", "details" ] } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "message": { "type": "string", "const": "No erasure request found for this memory." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/export": { "get": { "operationId": "export", "description": "Returns all projects and memories for the authenticated account in\nmachine-readable JSON format. Supports data portability requirements.\nEmbeddings are excluded as derivative data.\n\nUses streaming to keep memory usage constant regardless of account size.\n\nRate limited to 1 request per day per account.", "summary": "Export account data", "tags": [ "Export" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } } } } }, "\/memories\/feedback": { "post": { "operationId": "feedback", "tags": [ "Memories", "Feedback" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "maxLength": 128 }, "project_id": { "type": "string", "maxLength": 50 }, "memory_ids": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "minItems": 1, "maxItems": 50 } }, "required": [ "tenant_id", "project_id", "memory_ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer" } }, "required": [ "updated" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/memories": { "delete": { "operationId": "memory.bulkDestroy", "description": "Delete all memories for a tenant. Used for tenant erasure. Clears all storage layers\nand logs to audit trail.", "summary": "Bulk delete memories", "tags": [ "Memory" ], "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "project_id", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_-]+$", "maxLength": 50 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" } }, "required": [ "deleted" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "post": { "operationId": "memory.store", "description": "Store a new memory for a tenant within a project. Returns 201 for new memories,\n200 if duplicate content detected. Embedding generation is dispatched asynchronously.", "summary": "Create a memory", "tags": [ "Memory" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreMemoryRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "project_id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "source": { "type": "string" }, "metadata": { "type": "string" }, "embedding_status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "pending" ] } ] }, "expires_at": { "type": "string" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "number", "const": 1 } ] }, "staleness_score": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "last_accessed_at": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "active" ] } ] }, "superseded_by": { "type": [ "string", "null" ] }, "ttl_days": { "type": [ "string", "null" ] }, "soft_ttl_days": { "type": [ "string", "null" ] }, "pii_masked": { "type": "boolean" }, "pii_token_count": { "type": "integer" }, "version": { "type": "integer" }, "revision": { "type": "integer", "description": "Read-your-writes token (999.33): recall with wait_for_revision=\nguarantees this write is indexed before results are computed." }, "source_type": { "type": [ "string", "null" ], "description": "Provenance (CORR-09)" }, "source_ref": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "trust_state": { "description": "Belief-state (CORR-08)", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "proposed" ] } ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent identity (API-01)" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "conflicts": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "id", "content", "tenant_id", "project_id", "type", "importance", "tags", "source", "metadata", "embedding_status", "expires_at", "confidence", "staleness_score", "last_accessed_at", "status", "superseded_by", "ttl_days", "soft_ttl_days", "pii_masked", "pii_token_count", "version", "revision", "source_type", "source_ref", "observed_at", "verified_by", "verification_method", "trust_state", "agent_id", "created_at", "updated_at", "conflicts" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "project_id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "source": { "type": "string" }, "metadata": { "type": "string" }, "embedding_status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "pending" ] } ] }, "expires_at": { "type": "string" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "number", "const": 1 } ] }, "staleness_score": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "last_accessed_at": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "active" ] } ] }, "superseded_by": { "type": [ "string", "null" ] }, "ttl_days": { "type": [ "string", "null" ] }, "soft_ttl_days": { "type": [ "string", "null" ] }, "pii_masked": { "type": "boolean" }, "pii_token_count": { "type": "integer" }, "version": { "type": "integer" }, "revision": { "type": "integer", "description": "Read-your-writes token (999.33): recall with wait_for_revision=\nguarantees this write is indexed before results are computed." }, "source_type": { "type": [ "string", "null" ], "description": "Provenance (CORR-09)" }, "source_ref": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "trust_state": { "description": "Belief-state (CORR-08)", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "proposed" ] } ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent identity (API-01)" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "content", "tenant_id", "project_id", "type", "importance", "tags", "source", "metadata", "embedding_status", "expires_at", "confidence", "staleness_score", "last_accessed_at", "status", "superseded_by", "ttl_days", "soft_ttl_days", "pii_masked", "pii_token_count", "version", "revision", "source_type", "source_ref", "observed_at", "verified_by", "verification_method", "trust_state", "agent_id", "created_at", "updated_at" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "tenant_limit_reached" }, "message": { "type": "string" }, "max_tenants": { "type": "string" }, "tier": { "type": "string" } }, "required": [ "error", "message", "max_tenants", "tier" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_not_found" }, "message": { "type": "string", "const": "No project with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_id_required" }, "message": { "type": "string", "const": "Account has multiple projects \u2014 project_id is required." }, "available_projects": { "type": "string" } }, "required": [ "code", "message", "available_projects" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "no_project_found" }, "message": { "type": "string", "const": "No project found in your account. Create one in the dashboard or pass project_id." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "memory.index", "description": "Retrieve memories for a tenant within a project with optional filtering by type, tags,\nand importance. Results are paginated. Returns metadata only (no content field).", "summary": "List memories", "tags": [ "Memory" ], "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } }, { "name": "tags", "in": "query", "schema": { "type": "string" } }, { "name": "min_importance", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "importance", "updated_at" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "agent_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "memories": { "type": "string" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "memories", "total", "limit", "offset", "has_more" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/memories\/{id}\/supersede": { "post": { "operationId": "memory.supersede", "description": "Replace an existing memory with new content. The old memory is marked superseded\n(stops surfacing in search\/recall); the new memory inherits the old memory's type,\nimportance, tags, source, and metadata unless overridden. Works for all memory types \u2014\nuse this instead of POST \/memories when you are correcting or updating existing\nknowledge, so the audit trail is preserved.\n\nOptional header: If-Match: for optimistic locking against the old memory.", "summary": "Supersede a memory", "tags": [ "Memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SupersedeMemoryRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "project_id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "source": { "type": "string" }, "metadata": { "type": "string" }, "embedding_status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "pending" ] } ] }, "expires_at": { "type": "string" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "number", "const": 1 } ] }, "staleness_score": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "last_accessed_at": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "active" ] } ] }, "superseded_by": { "type": [ "string", "null" ] }, "ttl_days": { "type": [ "string", "null" ] }, "soft_ttl_days": { "type": [ "string", "null" ] }, "pii_masked": { "type": "boolean" }, "pii_token_count": { "type": "integer" }, "version": { "type": "integer" }, "revision": { "type": "integer", "description": "Read-your-writes token (999.33): recall with wait_for_revision=\nguarantees this write is indexed before results are computed." }, "source_type": { "type": [ "string", "null" ], "description": "Provenance (CORR-09)" }, "source_ref": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "trust_state": { "description": "Belief-state (CORR-08)", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "proposed" ] } ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent identity (API-01)" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "content", "tenant_id", "project_id", "type", "importance", "tags", "source", "metadata", "embedding_status", "expires_at", "confidence", "staleness_score", "last_accessed_at", "status", "superseded_by", "ttl_days", "soft_ttl_days", "pii_masked", "pii_token_count", "version", "revision", "source_type", "source_ref", "observed_at", "verified_by", "verification_method", "trust_state", "agent_id", "created_at", "updated_at" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "already_superseded" }, "message": { "type": "string", "const": "This memory has already been superseded" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "version_conflict" }, "message": { "type": "string" }, "current_version": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "current_version" ] } }, "required": [ "error" ] } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "memory_not_found" }, "message": { "type": "string", "const": "No memory with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/memories\/{id}\/chain": { "get": { "operationId": "memory.chain", "description": "Retrieve the full chain of predecessors and successors for any memory\nthat participates in a supersession chain.", "summary": "Get supersession chain", "tags": [ "Memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "chain": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "project_id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "source": { "type": "string" }, "metadata": { "type": "string" }, "embedding_status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "pending" ] } ] }, "expires_at": { "type": "string" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "number", "const": 1 } ] }, "staleness_score": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "last_accessed_at": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "active" ] } ] }, "superseded_by": { "type": [ "string", "null" ] }, "ttl_days": { "type": [ "string", "null" ] }, "soft_ttl_days": { "type": [ "string", "null" ] }, "pii_masked": { "type": "boolean" }, "pii_token_count": { "type": "integer" }, "version": { "type": "integer" }, "revision": { "type": "integer", "description": "Read-your-writes token (999.33): recall with wait_for_revision=\nguarantees this write is indexed before results are computed." }, "source_type": { "type": [ "string", "null" ], "description": "Provenance (CORR-09)" }, "source_ref": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "trust_state": { "description": "Belief-state (CORR-08)", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "proposed" ] } ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent identity (API-01)" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "content", "tenant_id", "project_id", "type", "importance", "tags", "source", "metadata", "embedding_status", "expires_at", "confidence", "staleness_score", "last_accessed_at", "status", "superseded_by", "ttl_days", "soft_ttl_days", "pii_masked", "pii_token_count", "version", "revision", "source_type", "source_ref", "observed_at", "verified_by", "verification_method", "trust_state", "agent_id", "created_at", "updated_at" ] } } }, "required": [ "chain" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "memory_not_found" }, "message": { "type": "string", "const": "No memory with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } } }, "\/memories\/{id}": { "get": { "operationId": "memory.show", "description": "Retrieve a single memory by ID, including full content from storage.", "summary": "Get a memory", "tags": [ "Memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "memory_not_found" }, "message": { "type": "string", "const": "No memory with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "memory.update", "description": "Update memory content, importance, tags, or metadata. Content changes trigger re-embedding.\nDecision-type memories cannot be updated (returns 405).", "summary": "Update a memory", "tags": [ "Memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateMemoryRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "project_id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "source": { "type": "string" }, "metadata": { "type": "string" }, "embedding_status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "pending" ] } ] }, "expires_at": { "type": "string" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "number", "const": 1 } ] }, "staleness_score": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "last_accessed_at": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "active" ] } ] }, "superseded_by": { "type": [ "string", "null" ] }, "ttl_days": { "type": [ "string", "null" ] }, "soft_ttl_days": { "type": [ "string", "null" ] }, "pii_masked": { "type": "boolean" }, "pii_token_count": { "type": "integer" }, "version": { "type": "integer" }, "revision": { "type": "integer", "description": "Read-your-writes token (999.33): recall with wait_for_revision=\nguarantees this write is indexed before results are computed." }, "source_type": { "type": [ "string", "null" ], "description": "Provenance (CORR-09)" }, "source_ref": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "trust_state": { "description": "Belief-state (CORR-08)", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "proposed" ] } ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent identity (API-01)" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "content", "tenant_id", "project_id", "type", "importance", "tags", "source", "metadata", "embedding_status", "expires_at", "confidence", "staleness_score", "last_accessed_at", "status", "superseded_by", "ttl_days", "soft_ttl_days", "pii_masked", "pii_token_count", "version", "revision", "source_type", "source_ref", "observed_at", "verified_by", "verification_method", "trust_state", "agent_id", "created_at", "updated_at" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "duplicate_content" }, "message": { "type": "string" }, "duplicate_id": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "duplicate_id" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "version_conflict" }, "message": { "type": "string" }, "current_version": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "current_version" ] } }, "required": [ "error" ] } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "memory_not_found" }, "message": { "type": "string", "const": "No memory with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "405": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "decision_immutable" }, "message": { "type": "string", "const": "Decision memories cannot be modified. Use POST \/v1\/memories\/{id}\/supersede instead." }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "memory.destroy", "description": "Permanently delete a memory and all associated data (content, embedding, index, cache).\nBy default this cascades to the memory's intelligence-derived child facts; the 200\nresponse body reports how many children were removed via {cascade_deleted: N}.\n\nQuery params:\n - dry_run=1 Preview only: deletes nothing, returns {dry_run, would_delete, ids}.\n - cascade=false Delete only this row, leaving derived children in place.", "summary": "Delete a memory", "tags": [ "Memory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "?dry_run=1 previews the cascade without deleting anything.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "deleted": { "type": "boolean" }, "cascade_deleted": { "type": "string" } }, "required": [ "deleted", "cascade_deleted" ] }, { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "would_delete": { "type": "string" }, "ids": { "type": "string" } }, "required": [ "dry_run", "would_delete", "ids" ] } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "memory_not_found" }, "message": { "type": "string", "const": "No memory with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } } }, "\/memories\/batch": { "post": { "operationId": "memoryBatch.store", "description": "Create up to 100 memories in a single request. Returns per-item results\nwith created\/duplicate\/error\/timeout status. Response is HTTP 200 when\nevery item succeeds, or HTTP 207 Multi-Status when at least one item\nerrored or timed out (74-03 supersedes D-02 \"always 200\").", "summary": "Batch create memories", "tags": [ "MemoryBatch" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BatchMemoryRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/memories\/{id}\/health": { "get": { "operationId": "memoryHealth.health", "description": "Returns the current health status of a memory including staleness score,\nhealth status, recommended action, and type-specific decay rate.", "summary": "Get memory health", "tags": [ "MemoryHealth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "memory_id": { "type": "string" }, "staleness_score": { "type": "integer" }, "health_status": { "type": "string", "enum": [ "fresh", "aging", "stale", "critical" ] }, "last_accessed_at": { "type": "string" }, "age_days": { "anyOf": [ { "type": "integer" }, { "type": "number" } ] }, "recommended_action": { "type": "string", "enum": [ "none", "review within 30 days", "verify accuracy -- content may be outdated", "immediate review -- memory likely unreliable", "unknown status" ] }, "decay_rate": { "type": "number" }, "type": { "type": "string" } }, "required": [ "memory_id", "staleness_score", "health_status", "last_accessed_at", "age_days", "recommended_action", "decay_rate", "type" ] } } } } } } }, "\/memories\/{id}\/refresh": { "post": { "operationId": "memoryHealth.refresh", "description": "Resets staleness score to 0 and updates the updated_at timestamp,\nsignaling that an agent has verified the memory is still accurate.\nReturns the updated health object.", "summary": "Refresh a memory", "tags": [ "MemoryHealth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "memory_id": { "type": "string" }, "staleness_score": { "type": "integer" }, "health_status": { "type": "string", "enum": [ "fresh", "aging", "stale", "critical" ] }, "last_accessed_at": { "type": "string" }, "age_days": { "anyOf": [ { "type": "integer" }, { "type": "number" } ] }, "recommended_action": { "type": "string", "enum": [ "none", "review within 30 days", "verify accuracy -- content may be outdated", "immediate review -- memory likely unreliable", "unknown status" ] }, "decay_rate": { "type": "number" }, "type": { "type": "string" } }, "required": [ "memory_id", "staleness_score", "health_status", "last_accessed_at", "age_days", "recommended_action", "decay_rate", "type" ] } } } } } } }, "\/namespaces\/{tenant_id}\/data-export": { "get": { "operationId": "namespaceExport", "description": "Uses streaming to keep memory usage constant regardless of namespace size.\n\nRate limited to 1 per day per account via throttle:export middleware.", "summary": "Export all memories for a namespace (tenant_id + project_id)", "tags": [ "NamespaceExport" ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/namespaces\/health": { "get": { "operationId": "namespaceHealth", "description": "Returns aggregate health statistics for all active memories within a\ntenant+project namespace, including counts by status, average staleness,\nand the top 5 stalest and healthiest memories.", "summary": "Get namespace health", "tags": [ "NamespaceHealth" ], "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "total_memories": { "type": "integer", "minimum": 0 }, "counts_by_status": { "type": "object", "properties": { "fresh": { "type": "string" }, "aging": { "type": "string" }, "stale": { "type": "string" }, "critical": { "type": "string" } }, "required": [ "fresh", "aging", "stale", "critical" ] }, "average_staleness": { "type": "number" }, "top_5_stalest": { "type": "string" }, "top_5_healthiest": { "type": "string" } }, "required": [ "total_memories", "counts_by_status", "average_staleness", "top_5_stalest", "top_5_healthiest" ] }, { "type": "object", "properties": { "total_memories": { "type": "integer" }, "counts_by_status": { "type": "object", "properties": { "fresh": { "type": "integer" }, "aging": { "type": "integer" }, "stale": { "type": "integer" }, "critical": { "type": "integer" } }, "required": [ "fresh", "aging", "stale", "critical" ] }, "average_staleness": { "type": "integer" }, "top_5_stalest": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "top_5_healthiest": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "total_memories", "counts_by_status", "average_staleness", "top_5_stalest", "top_5_healthiest" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/pii\/mask": { "post": { "operationId": "piiMask", "description": "POST \/v1\/pii\/mask\nBody: { \"contents\": [\"string1\", ...], \"tenant_id\": \"optional\" }", "summary": "Batch PII masking endpoint for sync clients", "tags": [ "PiiMask" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "maxLength": 255 }, "contents": { "type": "array", "items": { "type": "string", "maxLength": 10000 }, "minItems": 1, "maxItems": 100 } }, "required": [ "contents" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "masked_content": { "type": "string" }, "was_masked": { "type": "string" }, "token_count": { "type": "string" } }, "required": [ "masked_content", "was_masked", "token_count" ] } } }, "required": [ "results" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/projects": { "post": { "operationId": "project.store", "description": "Create a new project namespace for organizing memories.", "summary": "Create a project", "tags": [ "Project" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreProjectRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "consolidation_enabled": { "type": "boolean" }, "intelligence_enabled": { "type": "boolean" }, "masking_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "off" ] } ] }, "tool_egress_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "allow" ] } ] }, "memory_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "consolidation_enabled", "intelligence_enabled", "masking_policy", "tool_egress_policy", "memory_count", "created_at", "updated_at" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_name_taken" }, "message": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_limit_reached" }, "message": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "project.index", "description": "List all projects for the authenticated account with memory counts.", "summary": "List projects", "tags": [ "Project" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "consolidation_enabled": { "type": "boolean" }, "intelligence_enabled": { "type": "boolean" }, "masking_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "off" ] } ] }, "tool_egress_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "allow" ] } ] }, "memory_count": { "anyOf": [ { "type": "null" }, { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "consolidation_enabled", "intelligence_enabled", "masking_policy", "tool_egress_policy", "memory_count", "created_at", "updated_at" ] } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "projects", "total", "limit", "offset", "has_more" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/projects\/{id}": { "get": { "operationId": "project.show", "description": "Retrieve a single project by ID.", "summary": "Get a project", "tags": [ "Project" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "consolidation_enabled": { "type": "boolean" }, "intelligence_enabled": { "type": "boolean" }, "masking_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "off" ] } ] }, "tool_egress_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "allow" ] } ] }, "memory_count": { "anyOf": [ { "type": "null" }, { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "consolidation_enabled", "intelligence_enabled", "masking_policy", "tool_egress_policy", "memory_count", "created_at", "updated_at" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_not_found" }, "message": { "type": "string", "const": "No project with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "project.update", "description": "Update project settings including name, description, and consolidation_enabled.\nConsolidation requires a pro or team plan.", "summary": "Update a project", "tags": [ "Project" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateProjectRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "consolidation_enabled": { "type": "boolean" }, "intelligence_enabled": { "type": "boolean" }, "masking_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "off" ] } ] }, "tool_egress_policy": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "allow" ] } ] }, "memory_count": { "anyOf": [ { "type": "null" }, { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "consolidation_enabled", "intelligence_enabled", "masking_policy", "tool_egress_policy", "memory_count", "created_at", "updated_at" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_name_taken" }, "message": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "tier_restricted" }, "message": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_not_found" }, "message": { "type": "string", "const": "No project with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "project.destroy", "description": "Delete a project and cascade to all associated memories, embeddings, and cache.", "summary": "Delete a project", "tags": [ "Project" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_not_found" }, "message": { "type": "string", "const": "No project with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } } }, "\/projects\/{id}\/indexing": { "get": { "operationId": "project.indexing", "description": "Returns per-status counts of `memories_index.embedding_status` plus the\nage of the oldest still-pending memory. Used by ops dashboards, SDK\n\"wait until indexed\" loops, and Sentry-style alerts when pending backs up.", "summary": "Phase 999.33 \u2014 Indexing status snapshot for a project", "tags": [ "Project" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string" }, "pending": { "type": "string" }, "indexed": { "type": "string" }, "failed": { "type": "string" }, "oldest_pending_age_seconds": { "type": "number" } }, "required": [ "project_id", "pending", "indexed", "failed", "oldest_pending_age_seconds" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_not_found" }, "message": { "type": "string", "const": "No project with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } } }, "\/memories\/{id}\/promote": { "post": { "operationId": "promote", "description": "Transitions trust_state from proposed to verified, optionally moving the memory\nto a target namespace. Records promotion provenance for audit trail.", "summary": "Promote a memory from proposed to verified", "tags": [ "Promote" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PromoteMemoryRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "trust_state": { "type": "string" }, "tenant_id": { "type": "string" }, "verified_by": { "type": [ "string", "null" ] }, "verification_method": { "type": [ "string", "null" ] }, "metadata": { "type": [ "array", "null" ], "items": {} }, "project_id": { "type": "string" }, "type": { "type": "string" }, "importance": { "type": "integer" } }, "required": [ "id", "trust_state", "tenant_id", "verified_by", "verification_method", "metadata", "project_id", "type", "importance" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "content_hash_conflict" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "forbidden" }, "message": { "type": "string", "const": "You do not have access to this memory" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "memory_not_found" }, "message": { "type": "string", "const": "No memory with this ID exists" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } } } } }, "\/memories\/recall": { "post": { "operationId": "recall", "description": "Semantic search across memories using hybrid retrieval: PostgreSQL pre-filtering\nfollowed by cosine similarity scoring.", "summary": "Recall memories", "tags": [ "Recall" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RecallMemoriesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "total_candidates": { "type": "integer" }, "returned": { "type": "integer" }, "scoring": { "type": "string", "enum": [ "recency", "default" ] }, "query_cached": { "type": "boolean" }, "response_cached": { "type": "boolean" }, "degraded": { "type": "boolean" }, "indexing_wait_ms": { "type": "string" }, "indexing_wait_skipped": { "type": "boolean" }, "degraded_reason": { "type": [ "string", "null" ] }, "strategy_used": { "type": [ "string", "null" ] }, "sub_queries": { "type": [ "array", "null" ], "items": {} }, "reranked": { "type": [ "boolean", "null" ] }, "token_budget": { "type": "integer" }, "tokens_used": { "type": "string" } }, "required": [ "total_candidates", "returned", "scoring", "query_cached", "response_cached", "degraded", "indexing_wait_ms", "indexing_wait_skipped", "degraded_reason", "strategy_used", "sub_queries", "reranked", "token_budget", "tokens_used" ] }, "estimated_tokens": { "type": "integer" } }, "required": [ "data", "meta", "estimated_tokens" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "project_not_found" }, "message": { "type": "string", "const": "No project with this ID exists in your account" }, "docs": { "type": "string" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sessions": { "post": { "operationId": "session.start", "description": "Creates a session with a sess_ prefixed ULID.", "summary": "Start a new session", "tags": [ "Session" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StartSessionRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "agent_id": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": [ "array", "null" ], "items": {} }, "started_at": { "type": "string" }, "ended_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "account_id", "project_id", "agent_id", "tenant_id", "status", "metadata", "started_at", "ended_at", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sessions\/{id}": { "patch": { "operationId": "session.checkpoint", "description": "Merges new metadata with existing. Returns 409 if session is ended.", "summary": "Checkpoint (update) a session with new metadata", "tags": [ "Session" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CheckpointSessionRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "agent_id": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": [ "array", "null" ], "items": {} }, "started_at": { "type": "string" }, "ended_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "account_id", "project_id", "agent_id", "tenant_id", "status", "metadata", "started_at", "ended_at", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Session already ended" } }, "required": [ "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sessions\/{id}\/end": { "post": { "operationId": "session.end", "description": "Sets status=ended and ended_at. Dispatches GenerateSessionSummary\nif the session has associated memories. Returns 409 if already ended.", "summary": "End a session", "tags": [ "Session" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "agent_id": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": [ "array", "null" ], "items": {} }, "started_at": { "type": "string" }, "ended_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "account_id", "project_id", "agent_id", "tenant_id", "status", "metadata", "started_at", "ended_at", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Session already ended" } }, "required": [ "error" ] } } } } } } }, "\/sync\/push": { "post": { "operationId": "sync.push", "description": "DISABLED in v1.0: the apply-events-to-memories pipeline is not implemented,\nso accepting events would silently drop local memories on the cloud side.\nFull push implementation ships in v1.1. The route stays registered so\nclients get an explicit 501 (endpoint exists, not implemented) instead of\na 404 that looks like a configuration bug.\n\nValidation runs first (via SyncPushRequest) so that clients emitting a\nmalformed event_id get a 422 with an actionable error \u2014 not a misleading\n501 that hides the real problem. Canonical event_id is `evt_{ULID}`;\nlegacy UUIDs are accepted during the 6-month back-compat window (77-02).", "summary": "Push sync events to the cloud", "tags": [ "Sync" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SyncPushRequest" } } } }, "responses": { "501": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Sync push disabled in v1.0" }, "reason": { "type": "string", "const": "apply-events-to-memories not implemented" }, "expected_in": { "type": "string", "const": "v1.1" } }, "required": [ "error", "reason", "expected_in" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sync\/pull": { "get": { "operationId": "sync.pull", "description": "Returns events since the given cursor, ordered by sequence, with pagination.", "summary": "Pull sync events from the cloud", "tags": [ "Sync" ], "parameters": [ { "name": "namespace", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "cursor", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#\/components\/schemas\/SyncEvent" } }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "has_more": { "type": "boolean" } }, "required": [ "events", "cursor", "has_more" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/usage": { "get": { "operationId": "usage", "description": "Returns current period usage vs tier limits including memories, recalls, and projects.", "summary": "Get usage stats", "tags": [ "Usage" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "tier": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "hobby" ] } ] }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "memories_stored": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": "string" }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "used", "limit", "percentage" ] }, "recall_calls": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "string" }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "used", "limit", "percentage" ] }, "projects": { "type": "object", "properties": { "used": { "type": "string" }, "limit": { "type": "string" } }, "required": [ "used", "limit" ] } }, "required": [ "tier", "period_start", "period_end", "memories_stored", "recall_calls", "projects" ] } } } } } } }, "\/webhooks": { "post": { "operationId": "webhook.store", "description": "Subscribe to webhook events by providing a URL and list of event types.\nThe webhook secret is returned once in the response and never shown again.\nUse this secret to verify HMAC-SHA256 signatures on incoming payloads.", "summary": "Register a webhook", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RegisterWebhookRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": {} }, "secret": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "url", "events", "secret", "is_active", "created_at" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "webhook.index", "description": "Retrieve all webhooks registered for the authenticated account.\nThe webhook secret is never included in list responses.", "summary": "List webhooks", "tags": [ "Webhook" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "string" } }, "required": [ "webhooks" ] } } } } } } }, "\/webhooks\/{id}": { "delete": { "operationId": "webhook.destroy", "description": "Remove a webhook subscription. Associated delivery records are cascade-deleted.", "summary": "Delete a webhook", "tags": [ "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "BatchMemoryRequest": { "type": "object", "properties": { "memories": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000 }, "tenant_id": { "type": "string", "maxLength": 128 }, "project_id": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 }, "type": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] }, "importance": { "type": "integer", "minimum": 1, "maximum": 10 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "agent_id": { "type": [ "string", "null" ], "maxLength": 255 }, "session_id": { "type": [ "string", "null" ], "maxLength": 50 } }, "required": [ "content", "tenant_id", "project_id" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "memories" ], "title": "BatchMemoryRequest" }, "CheckpointSessionRequest": { "type": "object", "properties": { "metadata": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "checkpoint_note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "metadata" ], "title": "CheckpointSessionRequest" }, "ConfigureBootstrapRequest": { "type": "object", "properties": { "max_tokens": { "type": "integer", "minimum": 100, "maximum": 4000 }, "recency_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "include_types": { "type": "array", "items": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } }, "exclude_types": { "type": "array", "items": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } }, "role_config": { "type": "array", "items": { "type": "object", "properties": { "include_types": { "type": "array", "items": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } }, "max_tokens": { "type": "integer", "minimum": 100, "maximum": 4000 } } } } }, "title": "ConfigureBootstrapRequest" }, "PromoteMemoryRequest": { "type": "object", "properties": { "target_namespace": { "type": "string", "maxLength": 255 }, "promoted_by": { "type": "string", "maxLength": 255 } }, "title": "PromoteMemoryRequest" }, "RecallMemoriesRequest": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 1000 }, "tenant_id": { "type": "string", "maxLength": 128 }, "project_id": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "min_importance": { "type": "integer", "minimum": 1, "maximum": 10 }, "min_score": { "type": "number", "minimum": 0, "maximum": 1 }, "include_recency": { "type": "boolean" }, "strategy": { "type": "string", "enum": [ "default", "intelligent" ] }, "rerank": { "type": "boolean" }, "expand_context": { "type": "boolean" }, "trust_level": { "type": "string", "description": "Belief-state filter (CORR-08): only return memories at or above this trust level", "enum": [ "proposed", "verified", "disputed", "superseded", "expired" ] }, "namespace_recursive": { "type": "boolean" }, "prefer_compressed": { "type": "boolean" }, "wait_for_indexing": { "type": "boolean", "description": "Phase 999.33 \u2014 Strong-consistency read flag. When true, recall\nblocks for up to `wait_for_indexing_timeout_ms` (capped at 10s)\nuntil the project has zero `embedding_status='pending'` memories.\nReplaces canary write\u2192recall polling for clients that need\ndeterministic write-then-immediately-recall semantics." }, "wait_for_indexing_timeout_ms": { "type": "integer", "minimum": 0, "maximum": 10000 }, "wait_for_revision": { "type": "integer", "description": "Read-your-writes: pass the `revision` returned by a write to block\nuntil that write (and everything before it) is indexed. Later\nconcurrent writes never gate this caller.", "minimum": 0 }, "max_tokens": { "type": "integer", "description": "Token-budget recall (handoff Tier 1 #4): \"the best memories that\n fit in N tokens\" \u2014 the question a context-limited agent actually\nasks. Applied after scoring; items that don't fit fall back to\ntheir compressed summary, then drop. Combine with a higher limit.", "minimum": 100, "maximum": 100000 }, "types": { "type": "array", "items": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 }, "not_tags": { "type": "array", "description": "Negative tag filter + created_at date range (handoff Tier 3 #11)", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 }, "entity_ids": { "type": "array", "description": "RECALL-01: Filter by entity stable IDs", "items": { "type": "string", "maxLength": 100 }, "maxItems": 20 }, "used_ids": { "type": "array", "description": "Feedback signal (handoff Tier 2 #5): IDs from the PREVIOUS recall\nthat were actually useful \u2014 marks them used in the same round trip.", "items": { "type": "string", "maxLength": 50 }, "maxItems": 50 } }, "required": [ "query", "tenant_id", "project_id" ], "title": "RecallMemoriesRequest" }, "RegisterWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "memory.stale", "memory.critical", "namespace.health_degraded" ] }, "minItems": 1 } }, "required": [ "url", "events" ], "title": "RegisterWebhookRequest" }, "StartSessionRequest": { "type": "object", "properties": { "tenant_id": { "type": "string", "maxLength": 128 }, "project_id": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 }, "agent_id": { "type": [ "string", "null" ], "pattern": "^[a-z0-9_-]+$", "maxLength": 255 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "tenant_id" ], "title": "StartSessionRequest" }, "StoreMemoryRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000 }, "tenant_id": { "type": "string", "maxLength": 128 }, "project_id": { "type": "string", "pattern": "^[a-z0-9_-]+$", "maxLength": 50 }, "type": { "type": "string", "enum": [ "fact", "event", "pattern", "working", "decision", "preference", "context", "entity", "reference" ] }, "importance": { "type": "integer", "minimum": 1, "maximum": 10 }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "source_type": { "type": "string", "description": "Provenance fields (CORR-09)", "enum": [ "human", "agent", "import", "webhook", "system" ] }, "source_ref": { "type": [ "string", "null" ], "maxLength": 500 }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_by": { "type": [ "string", "null" ], "maxLength": 255 }, "verification_method": { "type": [ "string", "null" ], "maxLength": 100 }, "trust_state": { "type": "string", "description": "Belief-state (CORR-08)", "enum": [ "proposed", "verified", "disputed", "superseded", "expired" ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent identity (API-01)", "maxLength": 255 }, "session_id": { "type": [ "string", "null" ], "maxLength": 50 }, "mask": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "required": [ "content", "tenant_id" ], "title": "StoreMemoryRequest" }, "StoreProjectRequest": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "minLength": 1, "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "tool_egress_policy": { "type": "string", "description": "Sovereign mode \u2014 creation-time only. Restricted projects embed on\nthe EU-local sidecar; flipping later would mix incompatible vector\nspaces in one project, so UpdateProjectRequest deliberately omits it.", "enum": [ "allow", "restricted" ] } }, "required": [ "name" ], "title": "StoreProjectRequest" }, "SupersedeMemoryRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000 }, "importance": { "type": "integer", "minimum": 1, "maximum": 10 }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "required": [ "content" ], "title": "SupersedeMemoryRequest" }, "SyncEvent": { "type": "object", "properties": { "sequence": { "type": "integer" }, "event_id": { "type": "string" }, "account_id": { "type": "string" }, "namespace": { "type": "string" }, "event_type": { "type": "string" }, "memory_id": { "type": "string" }, "payload": { "type": "array", "items": {} }, "base_revision": { "type": [ "integer", "null" ] }, "source_device": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "sequence", "event_id", "account_id", "namespace", "event_type", "memory_id", "payload", "base_revision", "source_device", "created_at" ], "title": "SyncEvent" }, "SyncPushRequest": { "type": "object", "properties": { "namespace": { "type": "string", "maxLength": 255 }, "events": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^(evt_[0-9A-HJKMNP-TV-Z]{26}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "event_type": { "type": "string" }, "memory_id": { "type": "string" }, "payload": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "base_revision": { "type": [ "integer", "null" ] } }, "required": [ "event_id", "event_type", "memory_id", "payload" ] } } }, "required": [ "namespace", "events" ], "title": "SyncPushRequest" }, "UpdateMemoryRequest": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 10000 }, "importance": { "type": "integer", "minimum": 1, "maximum": 10 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "type": { "type": "string" }, "tenant_id": { "type": "string" }, "source_ref": { "type": [ "string", "null" ], "description": "Provenance fields (CORR-09)", "maxLength": 500 }, "verified_by": { "type": [ "string", "null" ], "maxLength": 255 }, "verification_method": { "type": [ "string", "null" ], "maxLength": 100 }, "trust_state": { "type": "string", "description": "Belief-state transition (CORR-08)", "enum": [ "proposed", "verified", "disputed", "superseded", "expired" ] }, "mask": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "title": "UpdateMemoryRequest" }, "UpdateProjectRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "consolidation_enabled": { "type": "boolean" }, "intelligence_enabled": { "type": "boolean" }, "masking_policy": { "type": "string", "enum": [ "off", "per_memory", "always" ] } }, "title": "UpdateProjectRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }