components: parameters: {} schemas: AdminDeleteScopeBody: properties: user_id: minLength: 1 type: string required: - user_id type: object AdminDeleteScopeResponse: properties: deleted: minimum: 0 type: integer required: - deleted type: object ErrorBasic: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object ErrorConfig400: description: Richer 400 envelope for PUT /v1/memories/config when startup-only fields are included. example: detail: Fields embedding_provider cannot be mutated at runtime — the embedding/LLM provider caches are fixed at first use. error: Provider/model selection is startup-only rejected: - embedding_provider properties: detail: type: string error: type: string rejected: items: type: string type: array required: - error - detail - rejected type: object ErrorConfig410: description: 410 Gone envelope for PUT /v1/memories/config when runtime mutation is disabled. example: detail: Set CORE_RUNTIME_CONFIG_MUTATION_ENABLED=true to enable runtime mutation in dev/test environments. error: PUT /v1/memories/config is deprecated for production properties: detail: type: string error: type: string required: - error - detail type: object ErrorUpstreamProvider: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object securitySchemes: adminBearerAuth: description: "Send `Authorization: Bearer ` on admin-only cleanup requests. This scheme is separate from normal client auth." scheme: bearer type: http bearerAuth: description: "Send `Authorization: Bearer ` on every request. The key is the deployment-wide secret configured via `CORE_API_KEY`; the middleware uses constant-time comparison." scheme: bearer type: http info: description: Semantic memory engine for AI applications. Request/response bodies are JSON; fields on the wire use snake_case. license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 title: AtomicMemory HTTP API version: 1.0.0 openapi: 3.1.0 paths: /v1/admin/scope: delete: description: Mounted only when CORE_ADMIN_API_KEY and CORE_TEST_SCOPE_ALLOW_PATTERN are both configured. The server refuses user_id values that do not match the configured test-scope pattern. operationId: deleteAdminScope requestBody: content: application/json: schema: properties: user_id: minLength: 1 type: string required: - user_id type: object required: true responses: "200": content: application/json: schema: properties: deleted: minimum: 0 type: integer required: - deleted type: object description: Number of memories deleted for the requested scope. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "401": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Missing or invalid bearer token "403": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Request is authenticated but not allowed "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error security: - adminBearerAuth: [] summary: Delete one allowed disposable test scope. tags: - Admin /v1/agents/conflicts: get: operationId: listAgentConflicts parameters: - description: Required. user_id. in: query name: user_id required: true schema: description: Required. user_id. minLength: 1 type: string responses: "200": content: application/json: schema: description: Open agent-trust conflicts for a user. properties: conflicts: items: additionalProperties: {} description: Memory conflict row from the repository. properties: auto_resolve_after: type: - string - "null" clarification_note: type: - string - "null" contradiction_confidence: type: number created_at: type: string existing_agent_id: type: - string - "null" existing_memory_id: type: - string - "null" existing_trust_level: type: - number - "null" id: type: string new_agent_id: type: - string - "null" new_memory_id: type: - string - "null" new_trust_level: type: - number - "null" resolution_policy: type: - string - "null" resolved_at: type: - string - "null" status: enum: - open - resolved_new - resolved_existing - resolved_both - auto_resolved type: string user_id: type: string required: - id - user_id - new_memory_id - existing_memory_id - new_agent_id - existing_agent_id - new_trust_level - existing_trust_level - contradiction_confidence - clarification_note - status - resolution_policy - resolved_at - created_at - auto_resolve_after type: object type: array count: type: number required: - conflicts - count type: object description: Conflicts list. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: List open agent conflicts for a user. tags: - Agents /v1/agents/conflicts/auto-resolve: post: operationId: autoResolveAgentConflicts requestBody: content: application/json: schema: description: Auto-resolve expired conflicts for a user. properties: user_id: description: Required. user_id. minLength: 1 type: string required: - user_id type: object required: true responses: "200": content: application/json: schema: description: Count of conflicts auto-resolved in the batch pass. properties: resolved: type: number required: - resolved type: object description: Count of resolved conflicts. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Auto-resolve all expired conflicts for a user. tags: - Agents /v1/agents/conflicts/{id}/resolve: put: operationId: resolveAgentConflict parameters: - in: path name: id required: true schema: minLength: 1 type: string requestBody: content: application/json: schema: description: Resolve a specific conflict with one of the three enum variants. properties: resolution: enum: - resolved_new - resolved_existing - resolved_both type: string required: - resolution type: object required: true responses: "200": content: application/json: schema: description: Resolved-conflict echo. properties: id: type: string status: enum: - resolved_new - resolved_existing - resolved_both type: string required: - id - status type: object description: Resolution confirmation. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Resolve a specific conflict with one of the three enum variants. tags: - Agents /v1/agents/trust: get: operationId: getAgentTrust parameters: - description: Required. agent_id. in: query name: agent_id required: true schema: description: Required. agent_id. minLength: 1 type: string - description: Required. user_id. in: query name: user_id required: true schema: description: Required. user_id. minLength: 1 type: string responses: "200": content: application/json: schema: description: (userId, agentId) trust record. properties: agent_id: type: string trust_level: type: number required: - agent_id - trust_level type: object description: Agent id + trust level. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Look up the trust level for a (user, agent) pair. tags: - Agents put: operationId: setAgentTrust requestBody: content: application/json: schema: description: Set the calling user's trust level for a given agent. trust_level in [0.0, 1.0]. properties: agent_id: description: Required. agent_id. minLength: 1 type: string display_name: type: string trust_level: description: Trust score in [0.0, 1.0]. maximum: 1 minimum: 0 type: number user_id: description: Required. user_id. minLength: 1 type: string required: - agent_id - user_id - trust_level type: object required: true responses: "200": content: application/json: schema: description: (userId, agentId) trust record. properties: agent_id: type: string trust_level: type: number required: - agent_id - trust_level type: object description: Agent id + applied trust level. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Set the calling user's trust level for a given agent. tags: - Agents /v1/capabilities: get: description: Unauthenticated. A protocol-level caller (e.g. a control-plane service) GETs this at startup to negotiate the core feature surface WITHOUT the JS SDK. Mirrors the SDK provider`s capabilities() descriptor over the wire. Like `/health`, it advertises a static capability surface (no user data), so it waives the document-level bearer requirement. operationId: getCapabilities responses: "200": content: application/json: schema: description: Wire capabilities descriptor. What the running core advertises to a protocol-level caller that negotiates at startup without the JS SDK. properties: deterministic_fast_path: type: boolean extensions: properties: health: type: boolean temporal: type: boolean versioning: type: boolean required: - health - versioning - temporal type: object ingest_modes: items: enum: - text - messages - verbatim type: string type: array retrieval: enum: - semantic type: string search: type: boolean version: type: integer required: - version - ingest_modes - search - retrieval - deterministic_fast_path - extensions type: object description: Capabilities descriptor. security: [] summary: Wire capabilities descriptor for protocol-level callers. tags: - Capabilities /v1/documents: get: description: "Returns active documents for the supplied `user_id`, ordered `(created_at DESC, id DESC)`. The opaque `cursor` is the `next_cursor` from the previous page (base64-url JSON tuple); malformed cursors return 400. The `status` query param buckets rows for the recovery surfaces: `'failed'` (any layer failed), `'unsupported'` (extraction marked unsupported), `'pending'` (extraction or semantic_index in pending/running), or `'all'` (default — every active row)." operationId: listDocumentsForUser parameters: - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: limit required: false schema: type: string - in: query name: cursor required: false schema: type: string - in: query name: status required: false schema: enum: - failed - unsupported - pending - all type: string responses: "200": content: application/json: schema: description: Cursor-paginated document list. properties: documents: items: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object type: array next_cursor: type: - string - "null" required: - documents - next_cursor type: object description: Cursor-paginated document list. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Cursor-paginated user-scoped document list with status-bucket filter. tags: - Documents post: description: Idempotent on (user_id, source_site, provider, external_id, provider_version). Returns 201 on first registration; 200 on a re-register that matches an active row. Registration accepts `storage_mode = 'pointer_only'`; managed_blob and inline_small_text return 400. operationId: registerDocument requestBody: content: application/json: schema: additionalProperties: false description: Register a document pointer. Document registration accepts pointer_only mode; managed_blob and inline_small_text return 400. properties: account_id: type: - string - "null" consent_policy: additionalProperties: true type: object content_hash: type: - string - "null" display_name: type: - string - "null" external_id: description: Required. external_id. minLength: 1 type: string external_uri: type: - string - "null" extraction_status: description: Initial extraction-layer state at register time. 'pending' = caller intends to extract; 'not_required' = pointer-only flow (default); 'unsupported' = caller knows the file type cannot be extracted. Service-owned values ('running', 'complete', 'failed') are rejected. enum: - pending - not_required - unsupported type: string metadata: additionalProperties: true type: object mime_type: type: - string - "null" provider: description: Required. provider. minLength: 1 type: string provider_version: type: - string - "null" retention_policy: additionalProperties: true type: object semantic_index_status: description: Initial semantic-index-layer state at register time. 'pending' = caller intends to index; 'not_required' = no indexing planned. Service-owned transitions handle 'running', 'complete', 'failed', 'stale'. enum: - pending - not_required type: string size_bytes: minimum: 0 type: integer source_modified_at: format: date-time type: string source_site: description: Required. source_site. minLength: 1 type: string storage_mode: enum: - pointer_only type: string user_id: description: Required. user_id. minLength: 1 type: string required: - user_id - source_site - provider - external_id type: object required: true responses: "200": content: application/json: schema: description: "Document registration result. `created: true` when a new row was inserted; `false` when an active row with the same (user, source, external_id, version) already existed." properties: created: type: boolean document: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object required: - document - created type: object description: Idempotent re-registration; document already existed. "201": content: application/json: schema: description: "Document registration result. `created: true` when a new row was inserted; `false` when an active row with the same (user, source, external_id, version) already existed." properties: created: type: boolean document: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object required: - document - created type: object description: Document registered. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Register a pointer-only document. tags: - Documents /v1/documents/limits: get: description: Public preflight surface. Clients call this to size requests and decide whether to attempt a managed-blob upload. The values are a composition-time snapshot of the runtime config; no PII, no per-user state. Mirrors the auth posture of `/health`. operationId: getDocumentLimits responses: "200": content: application/json: schema: description: Document upload/index limits and raw-storage capability. Public preflight surface — clients read this to size requests and decide whether to attempt a managed-blob upload. When a managed-blob adapter is configured, `raw_storage` additionally advertises the active store's `provider` + capability triple (`addressing`, `retrieval_consistency`, `delete_semantics`) so clients can render honest copy for eventual-provider flows. No PII, no per-user state. properties: index_max_text_bytes: exclusiveMinimum: 0 type: integer raw_storage: properties: addressing: enum: - location - content type: string delete_semantics: enum: - delete - unpin - tombstone type: string enabled: type: boolean mode: enum: - pointer_only - managed_blob type: string provider: type: string reason: type: string retrieval_consistency: enum: - immediate - eventual type: string supports_get: type: boolean supports_head: type: boolean required: - enabled - mode type: object raw_upload_max_bytes: exclusiveMinimum: 0 type: integer required: - raw_upload_max_bytes - index_max_text_bytes - raw_storage type: object description: Document limits + raw_storage capability. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Read upload + index byte caps and raw-storage capability. tags: - Documents /v1/documents/list: get: operationId: listDocuments parameters: - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: source_site required: false schema: type: string - in: query name: limit required: false schema: type: string - in: query name: offset required: false schema: type: string responses: "200": content: application/json: schema: description: Paginated document list. properties: count: type: number documents: items: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object type: array required: - documents - count type: object description: Document list with count. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: List active documents for a user, optionally filtered by source_site. tags: - Documents /v1/documents/passport-feed: get: description: "Single SQL UNION ALL: one row per documentId-with-memories (grouped on `raw_document_id`, joined to `raw_documents` for the status envelope) plus 1:1 standalone-memory rows (memories whose `raw_document_id IS NULL`). Sorted by `(sort_at DESC, sort_id DESC)`; the webapp passport route consumes this as the memory-feed stream of its server-side two-stream merge. Cursor + limit semantics match the other document list routes; opaque `next_cursor` is the tuple of the last consumed row." operationId: listPassportFeed parameters: - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: limit required: false schema: type: string - in: query name: cursor required: false schema: type: string responses: "200": content: application/json: schema: description: "Passport feed: grouped memory-backed document rows + 1:1 standalone memory rows, unioned and ordered by (sort_at DESC, sort_id DESC). `next_cursor` is the opaque continuation cursor; null indicates the stream is exhausted." properties: next_cursor: type: - string - "null" rows: items: description: Passport-feed row (document_grouped or standalone_memory). oneOf: - properties: chunk_count: minimum: 0 type: integer delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" document_id: type: string extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string kind: enum: - document_grouped type: string last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" mime_type: type: - string - "null" raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string representative: properties: content: type: string created_at: type: string id: type: string source_site: type: - string - "null" required: - id - content - created_at - source_site type: object semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string sort_at: type: string sort_id: type: string storage_provider: type: - string - "null" required: - kind - document_id - sort_at - sort_id - representative - chunk_count - raw_storage_status - extraction_status - semantic_index_status - last_error - display_name - mime_type - storage_provider - raw_storage_metadata - delete_semantics type: object - properties: kind: enum: - standalone_memory type: string memory: properties: content: type: string created_at: type: string id: type: string source_site: type: - string - "null" required: - id - content - created_at - source_site type: object sort_at: type: string sort_id: type: string required: - kind - sort_at - sort_id - memory type: object type: array required: - rows - next_cursor type: object description: Passport feed page. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: "Memory-backed passport feed: grouped doc rows + standalone memories." tags: - Documents /v1/documents/without-memories: get: description: Backs the passport synthetic-row stream and the UI "uploaded but unindexed" surface. A row appears when it has zero non-deleted memories AND at least one layer status sits in the supplied filter. Filter omitted -> server default 'recovery-relevant set (extraction in pending/failed/unsupported, semantic_index in pending/failed, raw_storage in raw_storage_failed). Cursor + limit semantics match `GET /v1/documents`. operationId: listDocumentsWithoutMemories parameters: - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: limit required: false schema: type: string - in: query name: cursor required: false schema: type: string - in: query name: extraction required: false schema: type: string - in: query name: semantic_index required: false schema: type: string - in: query name: raw_storage required: false schema: type: string responses: "200": content: application/json: schema: description: Cursor-paginated document list. properties: documents: items: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object type: array next_cursor: type: - string - "null" required: - documents - next_cursor type: object description: Cursor-paginated unbacked-document list. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Documents WITHOUT non-deleted memories, narrowed by recovery-status filter. tags: - Documents /v1/documents/{id}: delete: description: "Idempotent: a second DELETE on the same id returns success with `already_deleted: true`. Subsequent GETs of the deleted id return 404." operationId: deleteDocument parameters: - in: path name: id required: true schema: format: uuid type: string - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: "Document soft-delete acknowledgement. `already_deleted: true` when the row was missing or previously tombstoned (idempotent on repeat calls)." properties: already_deleted: type: boolean success: enum: - true type: boolean required: - success - already_deleted type: object description: Soft-delete acknowledgement. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Soft-delete (tombstone) a document. tags: - Documents get: operationId: getDocument parameters: - in: path name: id required: true schema: format: uuid type: string - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object description: Document record. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Document not found "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Fetch a single document by UUID. tags: - Documents /v1/documents/{id}/extraction-failure: post: description: "Service-owned status transition: callers declare *that* extraction failed and *what category* via a bounded `error_code`. The route service-truncates `error_message` to a fixed cap and rejects arbitrary status combinations. Idempotent on retry; 409 on invalid source state with the row's current per-layer status echoed in the response body." operationId: markExtractionFailure parameters: - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: additionalProperties: false description: Constrained transition body for the extraction-failure route. The route loads the row under a per-document advisory lock, verifies the current state is one of the allowed source states, and writes `extraction_status="failed"` + `semantic_index_status="not_required"` + a sanitised `last_error.layer="extraction"`. 409 on invalid transitions; idempotent on repeat for already-failed rows. properties: error_code: description: Bounded extraction-layer failure code. Open-ended exception messages ride on `error_message`; this code is what the UI / metrics layer pivots on. enum: - parser_threw - parser_timeout - parser_oom - unsupported_encoding - corrupt_input - unknown type: string error_message: type: string user_id: description: Required. user_id. minLength: 1 type: string required: - user_id - error_code - error_message type: object required: true responses: "200": content: application/json: schema: description: "Constrained-transition acknowledgement. The persisted row is echoed so callers can read back the durable status they just wrote. `idempotent: true` when the row was already in the failed state and the call only refreshed `last_error`." properties: document: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object idempotent: type: boolean required: - document - idempotent type: object description: Marker write acknowledgement; durable row echoed. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Document not found "409": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Invalid extraction state transition. The response body echoes `current.{raw_storage_status,extraction_status,semantic_index_status}` so the caller can reason about retries. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Mark the document as extraction-failed. tags: - Documents /v1/documents/{id}/index: post: description: "Deterministic char-window chunking, batched embeddings via the core embedding provider, and one provenance-linked memory per chunk. Idempotent on byte-identical text under the current chunker_version: the response's `idempotent_skip` flag indicates whether work was performed. A re-index with new text soft-deletes the prior generation of chunks + derived memories before inserting the fresh one." operationId: indexDocument parameters: - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: description: Chunk + embed the supplied text for the registered document, creating one provenance-linked memory per chunk. Idempotent on byte-identical text under the current chunker_version. properties: text: description: Required. text. minLength: 1 type: string user_id: description: Required. user_id. minLength: 1 type: string required: - user_id - text type: object required: true responses: "200": content: application/json: schema: description: "Text indexing result. `indexed_content_hash` is the SHA-256 of the indexed text and is stored on the document as `indexed_content_hash` (distinct from the upstream/provider `content_hash`). `idempotent_skip: true` when the input matched the prior indexed text under the current chunker_version (no fresh chunks or memories created); otherwise the prior generation was soft-deleted and the counts reflect the new generation." properties: chunker_version: type: string chunks_created: type: number document_id: type: string idempotent_skip: type: boolean indexed_content_hash: type: string memories_created: type: number parser_version: type: string required: - document_id - indexed_content_hash - chunks_created - memories_created - idempotent_skip - chunker_version - parser_version type: object description: Indexing result with chunk + memory counts. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Document not found "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Chunk + embed text for a registered document. tags: - Documents /v1/documents/{id}/index-failure: post: description: Service-owned status transition. The `index_text_too_large` code on a `extraction_status='pending'` row atomically advances extraction to `'complete'` AND writes `semantic_index_status='failed'` so the durable row reflects the upload-pipeline sequence. Idempotent on retry; 409 on invalid source state. operationId: markIndexFailure parameters: - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: additionalProperties: false description: 'Constrained transition body for the index-failure route. Permitted transitions: (a) `extraction_status="complete"` + `semantic_index_status="pending"` -> writes `semantic_index_status="failed"`; (b) `extraction_status="pending"` + `semantic_index_status="pending"` AND `error_code="index_text_too_large"` -> atomically writes `extraction_status="complete"` + `semantic_index_status="failed"`; (c) idempotent retry on already-failed rows. Any other state returns 409.' properties: error_code: description: Bounded semantic-index-layer failure code. `index_text_too_large` is the upload-pipeline shortcut for the case where extracted text exceeded the index byte cap before reaching `POST /:id/index`. enum: - index_text_too_large - extraction_empty - unknown type: string error_message: type: string user_id: description: Required. user_id. minLength: 1 type: string required: - user_id - error_code - error_message type: object required: true responses: "200": content: application/json: schema: description: "Constrained-transition acknowledgement. The persisted row is echoed so callers can read back the durable status they just wrote. `idempotent: true` when the row was already in the failed state and the call only refreshed `last_error`." properties: document: description: Document registry record. snake_case wire format. properties: content_hash: type: - string - "null" created_at: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" display_name: type: - string - "null" external_id: type: string external_uri: type: - string - "null" extraction_status: enum: - not_required - pending - running - complete - unsupported - failed type: string id: type: string indexed_at: type: - string - "null" indexed_content_hash: type: - string - "null" last_error: properties: code: type: string layer: enum: - raw_storage - extraction - semantic_index type: string message: type: string occurred_at: type: string required: - layer - code - message - occurred_at type: - object - "null" metadata: additionalProperties: {} type: object mime_type: type: - string - "null" provider_version: type: - string - "null" raw_source_id: type: string raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - pointer_recorded - blob_stored - inline_text_stored - raw_storage_failed - blob_deleted - blob_pending - blob_available - blob_archival_failed - blob_tombstoned type: string registration_status: enum: - registered - registration_failed type: string semantic_index_status: enum: - not_required - pending - running - complete - failed - stale type: string size_bytes: type: - number - "null" source_modified_at: type: - string - "null" storage_artifact_id: format: uuid type: - string - "null" storage_mode: enum: - pointer_only - managed_blob - inline_small_text type: string storage_provider: type: - string - "null" storage_uri: type: - string - "null" updated_at: type: string user_id: type: string required: - id - user_id - raw_source_id - external_id - external_uri - display_name - mime_type - size_bytes - content_hash - provider_version - source_modified_at - storage_mode - storage_uri - storage_provider - registration_status - raw_storage_status - raw_storage_metadata - delete_semantics - metadata - created_at - updated_at - indexed_content_hash - indexed_at - extraction_status - semantic_index_status - last_error - storage_artifact_id type: object idempotent: type: boolean required: - document - idempotent type: object description: Marker write acknowledgement; durable row echoed. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Document not found "409": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Invalid index state transition; current per-layer status echoed. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Mark the document as index-failed. tags: - Documents /v1/documents/{id}/raw: put: description: Stores the request body as the document's managed blob via the configured `RawContentStore` adapter (`local_fs` or `s3`), and promotes the document row to `storage_mode='managed_blob'` / `raw_storage_status='blob_stored'`. Idempotent on byte-identical input under the same document. Different bytes against an already-stored managed blob return 409 because the managed slot is immutable per row to avoid orphaning the prior blob. Returns 503 when the deployment runs `rawStorageMode='pointer_only'`. operationId: uploadRawDocument parameters: - in: path name: id required: true schema: format: uuid type: string - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: content_type required: false schema: type: string requestBody: content: application/octet-stream: schema: format: binary type: string required: true responses: "200": content: application/json: schema: description: "Managed-blob upload result. The document row is now `storage_mode='managed_blob'` with `raw_storage_status` set to `'blob_stored'` (immediate providers — local_fs, s3), `'blob_pending'` (eventual providers awaiting the reconciler), or `'blob_available'` (gateway-confirmed retrievable on Filecoin). `content_hash` is the SHA-256 of the PLAINTEXT bytes (distinct from `indexed_content_hash` and from the encoded-byte hash the codec writes under `raw_storage_metadata.codec`, which is internal). `raw_storage_metadata` is the public allowlist (codec name+version + Synapse filecoin allowlist with flattened copy_count/provider_ids/copy_statuses — internal sidecars stripped). `delete_semantics` advertises what AtomicMemory's DELETE call will do at the provider boundary for this row. `idempotent_skip: true` when the same bytes were already attached to this document." properties: content_hash: type: string delete_semantics: description: What AtomicMemory's DELETE call does at the provider boundary for this row's storage_provider. `'delete'` = adapter issues the provider's removal operation; `'unpin'` = removes AtomicMemory's pin but the provider's other peers may continue to serve; `'tombstone'` = AtomicMemory stops managing the bytes but the decentralized network may still serve. `null` for pointer-only rows or providers not registered for cleanup. enum: - delete - unpin - tombstone - null type: - string - "null" document_id: type: string idempotent_skip: type: boolean raw_storage_metadata: additionalProperties: false description: "Public-facing raw_storage_metadata. STRICTLY allowlisted: codec emits only name+version (AES-GCM internals never reach the wire); filecoin emits public fields (ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — `ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint populated by drivers that derive one alongside the PieceCID; the canonical storage URI stays `filecoin://piece/` regardless. The internal structured copies[{provider_id,status}] shape is flattened at the formatter; upload_result and other internal sidecars are NEVER emitted. The schema is deny-by-default (`.strict()`) at every level — a formatter regression that lets unknown keys through fails response-shape validation." properties: codec: additionalProperties: false properties: name: enum: - none - aes_gcm type: string version: type: number required: - name - version type: object filecoin: additionalProperties: false properties: copy_count: minimum: 0 type: integer copy_statuses: items: type: string type: array ipfs_cid: type: string piece_cid: type: string provider_ids: items: type: string type: array type: object type: object raw_storage_status: enum: - blob_stored - blob_pending - blob_available type: string size_bytes: type: number storage_mode: enum: - managed_blob type: string storage_provider: type: string storage_uri: type: string required: - document_id - storage_provider - storage_uri - content_hash - size_bytes - raw_storage_status - storage_mode - raw_storage_metadata - delete_semantics - idempotent_skip type: object description: Upload result with storage URI + content hash + size. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Document not found "409": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: "Conflict: the document already has a managed blob with a different content_hash. Register a fresh document for the new bytes — the existing blob is not overwritten." "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Upload managed raw bytes for a registered document. tags: - Documents /v1/entities: get: description: Returns all distinct entity IDs for the authenticated deployment, ordered by most recently active. Paginated via `page` and `page_size`. operationId: listEntities parameters: - in: query name: entity_type required: false schema: enum: - user - agent - session type: string - in: query name: page required: false schema: default: 1 minimum: 1 type: integer - in: query name: page_size required: false schema: default: 50 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Paginated entity list. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: List all entities with memory counts. tags: - Entities /v1/entities/merge: post: description: Re-scopes all memories, attributes, cards, and graph edges from `source` to `target` in a single transaction, then deletes the source entity. operationId: mergeEntities requestBody: content: application/json: schema: properties: source: properties: entity_id: minLength: 1 type: string entity_type: enum: - user - agent - session type: string required: - entity_type - entity_id type: object target: properties: entity_id: minLength: 1 type: string entity_type: enum: - user - agent - session type: string required: - entity_type - entity_id type: object required: - source - target type: object required: true responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Counts of records moved per table. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Merge a source entity into a target entity. tags: - Entities /v1/entities/{entity_type}/{entity_id}: delete: description: Deletes memories, entity attributes, user profile, entity graph records, entity edges, and entity cards for the given entity ID. Idempotent — returns zero counts if the entity does not exist. operationId: deleteEntity parameters: - in: path name: entity_type required: true schema: enum: - user - agent - session type: string - in: path name: entity_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Deleted row counts per table. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Cascade-delete all data for an entity. tags: - Entities get: description: Pass `?entity_name=` to resolve entity relations for a specific named entity in the user's graph. Without `entity_name`, `relations` is always `[]` because entity-graph lookup requires a semantic name, not an opaque user_id. operationId: getEntity parameters: - in: path name: entity_type required: true schema: enum: - user - agent - session type: string - in: path name: entity_id required: true schema: minLength: 1 type: string - in: query name: entity_name required: false schema: minLength: 1 type: string responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Entity detail with attribute triples, relation edges, and recent entity cards. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Get entity detail — attributes, relations, and recent cards. tags: - Entities /v1/entities/{entity_type}/{entity_id}/attributes: get: description: Returns `(entity, attribute, value, type)` triples extracted from memories. Pass `?attribute=` to filter by a specific attribute. Returns an empty array when `ENTITY_ATTRIBUTES_ENABLED` is off. operationId: getEntityAttributes parameters: - in: path name: entity_type required: true schema: enum: - user - agent - session type: string - in: path name: entity_id required: true schema: minLength: 1 type: string - in: query name: attribute required: false schema: minLength: 1 type: string - in: query name: entity required: false schema: minLength: 1 type: string - in: query name: limit required: false schema: default: 50 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Attribute triples ordered by observed_at DESC. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Get structured attribute triples for an entity. tags: - Entities /v1/entities/{entity_type}/{entity_id}/memories/{memory_id}/history: get: description: Surfaces the full AUDN version chain for a memory — ADD, UPDATE, SUPERSEDE events in chronological order. operationId: getMemoryHistory parameters: - in: path name: entity_type required: true schema: enum: - user - agent - session type: string - in: path name: entity_id required: true schema: minLength: 1 type: string - in: path name: memory_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Ordered mutation history for the memory. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Memory not found "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Get the mutation history of a single memory record. tags: - Entities /v1/entities/{entity_type}/{entity_id}/profile: get: description: Returns the auto-synthesized prose profile from `user_profiles` plus top structured attribute triples from `entity_attributes`. No LLM call on the read path — the profile is pre-computed at ingest time. `profile` is `null` when fewer than 3 memories have been ingested or when `USER_PROFILE_CHANNEL_ENABLED` is off. operationId: getEntityProfile parameters: - in: path name: entity_type required: true schema: enum: - user - agent - session type: string - in: path name: entity_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Entity profile with attributes and memory count. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Get the synthesized profile for a user or agent. tags: - Entities /v1/entities/{entity_type}/{entity_id}/settings: patch: description: Stores an extraction prompt (up to 1,500 chars) and pipeline overrides for a specific entity. Returns 503 when `entity_settings` is not yet wired into the runtime. operationId: patchEntitySettings parameters: - in: path name: entity_type required: true schema: enum: - user - agent - session type: string - in: path name: entity_id required: true schema: minLength: 1 type: string requestBody: content: application/json: schema: properties: decay_enabled: type: boolean extraction_prompt: maxLength: 1500 type: string memory_kinds: items: type: string type: array type: object required: true responses: "200": content: application/json: schema: additionalProperties: {} properties: {} type: object description: Updated entity settings row. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "503": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Entity settings feature not enabled on this deployment. summary: Update per-entity extraction guidance and pipeline config. tags: - Entities /v1/memories/audit/recent: get: operationId: getRecentAudit parameters: - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: limit required: false schema: type: string responses: "200": content: application/json: schema: description: Newest-first mutation rows for a user. properties: count: type: number mutations: items: additionalProperties: {} description: Claim-version row (one snapshot in a memory's history). properties: actor_model: type: - string - "null" claim_id: type: string content: type: string contradiction_confidence: type: - number - "null" created_at: type: string embedding: items: type: number type: array episode_id: type: - string - "null" id: type: string importance: type: number memory_id: type: - string - "null" mutation_reason: type: - string - "null" mutation_type: enum: - add - update - supersede - delete - clarify - null type: - string - "null" previous_version_id: type: - string - "null" source_site: type: string source_url: type: string superseded_by_version_id: type: - string - "null" user_id: type: string valid_from: type: string valid_to: type: - string - "null" required: - id - claim_id - user_id - content - embedding - importance - source_site - source_url - valid_from - created_at type: object type: array required: - mutations - count type: object description: Recent mutations. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Recent mutations for a user, limit-bounded. tags: - Audit /v1/memories/audit/summary: get: operationId: getAuditSummary parameters: - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Aggregate mutation statistics for a user. properties: active_versions: type: number by_mutation_type: additionalProperties: type: number type: object superseded_versions: type: number total_claims: type: number total_versions: type: number required: - total_versions - active_versions - superseded_versions - total_claims - by_mutation_type type: object description: Mutation summary. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Aggregate mutation statistics for a user's memory store. tags: - Audit /v1/memories/by-external-id/{externalId}: get: description: Reverse lookup of a memory by its `metadata.externalId`, scoped to `user_id`. the caller stamps its own id into `metadata.externalId` on quick-ingest; this resolves that id back to the core memory. Returns the same body as GET /v1/memories/{id}. operationId: getMemoryByExternalId parameters: - in: path name: externalId required: true schema: maxLength: 256 minLength: 1 type: string - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: additionalProperties: {} description: Full memory row as emitted by core. properties: access_count: type: number agent_id: type: - string - "null" content: type: string created_at: type: string deleted_at: type: - string - "null" embedding: items: type: number type: array episode_id: type: - string - "null" expired_at: type: - string - "null" id: type: string importance: type: number keywords: type: string last_accessed_at: type: string memory_type: type: string metadata: additionalProperties: {} type: object namespace: type: - string - "null" network: {} observation_subject: type: - string - "null" observed_at: type: string opinion_confidence: type: - number - "null" overview: type: string source_site: type: string source_url: type: string status: enum: - active - needs_clarification type: string summary: type: string trust_score: type: number user_id: type: string visibility: enum: - agent_only - restricted - workspace - null type: - string - "null" workspace_id: type: - string - "null" required: - id - user_id - content - embedding - memory_type - importance - source_site - source_url - status - metadata - keywords - summary - overview - trust_score - observed_at - created_at - last_accessed_at - access_count type: object description: Memory object. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Memory not found "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Fetch a single memory by caller-owned metadata.externalId. tags: - Memories /v1/memories/cap: get: operationId: checkMemoryCap parameters: - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Memory cap status and recommendation. properties: active_memories: type: number max_memories: type: number recommendation: enum: - none - consolidate - decay - consolidate-and-decay type: string status: enum: - ok - warn - exceeded type: string usage_ratio: type: number required: - active_memories - max_memories - status - usage_ratio - recommendation type: object description: Cap status. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Memory-cap status for a user's store. tags: - Lifecycle /v1/memories/config: put: description: Set CORE_RUNTIME_CONFIG_MUTATION_ENABLED=true to enable. Startup-only fields (embedding_provider/model, llm_provider/model) return 400 with a `rejected` array listing the offending fields. operationId: updateConfig requestBody: content: application/json: schema: additionalProperties: {} description: Runtime config mutation. See handler for 410 and rejected[] paths. properties: {} type: object required: true responses: "200": content: application/json: schema: description: Applied config updates + full post-update snapshot. properties: applied: items: type: string type: array config: description: Runtime config snapshot returned by /health + /config. properties: agentic_retrieval_enabled: type: boolean clarification_conflict_threshold: type: number cross_encoder_enabled: type: boolean embedding_model: type: string embedding_provider: type: string entity_graph_enabled: type: boolean hybrid_search_enabled: type: boolean iterative_retrieval_enabled: type: boolean llm_model: type: string llm_provider: type: string max_search_results: type: number repair_loop_enabled: type: boolean retrieval_profile: type: string voyage_document_model: type: string voyage_query_model: type: string required: - retrieval_profile - embedding_provider - embedding_model - voyage_document_model - voyage_query_model - llm_provider - llm_model - clarification_conflict_threshold - max_search_results - hybrid_search_enabled - iterative_retrieval_enabled - entity_graph_enabled - cross_encoder_enabled - agentic_retrieval_enabled - repair_loop_enabled type: object note: type: string required: - applied - config - note type: object description: Applied changes + config snapshot. "400": content: application/json: schema: oneOf: - $ref: "#/components/schemas/ErrorBasic" - $ref: "#/components/schemas/ErrorConfig400" description: Input validation error OR startup-only fields were supplied. "410": content: application/json: schema: description: 410 Gone envelope for PUT /v1/memories/config when runtime mutation is disabled. example: detail: Set CORE_RUNTIME_CONFIG_MUTATION_ENABLED=true to enable runtime mutation in dev/test environments. error: PUT /v1/memories/config is deprecated for production properties: detail: type: string error: type: string required: - error - detail type: object description: Runtime config mutation is disabled in production. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Mutate runtime config (dev/test only). 410 when disabled. tags: - Configuration /v1/memories/consolidate: post: operationId: consolidateMemories requestBody: content: application/json: schema: properties: execute: type: boolean user_id: description: Required. user_id. minLength: 1 type: string required: - user_id type: object required: true responses: "200": content: application/json: schema: anyOf: - description: Consolidation dry-run (execute=false). properties: clusters: items: properties: avg_affinity: type: number member_contents: items: type: string type: array member_count: type: number member_ids: items: type: string type: array required: - member_ids - member_contents - avg_affinity - member_count type: object type: array clusters_found: type: number memories_in_clusters: type: number memories_scanned: type: number required: - memories_scanned - clusters_found - memories_in_clusters - clusters type: object - description: Consolidation execution result (execute=true). properties: clusters_consolidated: type: number consolidated_memory_ids: items: type: string type: array memories_archived: type: number memories_created: type: number required: - clusters_consolidated - memories_archived - memories_created - consolidated_memory_ids type: object description: Consolidation result — scan or execute. description: Consolidation result. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Compute consolidation candidates; optionally execute (execute=true). tags: - Lifecycle /v1/memories/decay: post: operationId: evaluateDecay requestBody: content: application/json: schema: properties: dry_run: type: boolean user_id: description: Required. user_id. minLength: 1 type: string required: - user_id type: object required: true responses: "200": content: application/json: schema: description: Decay evaluation (+ archive count when not dry-run). properties: archived: type: number avg_retention_score: type: number candidates_for_archival: items: properties: access_count: type: number content: type: string days_since_access: type: number id: type: string importance: type: number retention_score: type: number required: - id - content - retention_score - importance - days_since_access - access_count type: object type: array memories_evaluated: type: number retention_threshold: type: number required: - memories_evaluated - candidates_for_archival - retention_threshold - avg_retention_score - archived type: object description: Decay evaluation + archived count. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Evaluate decay candidates. dry_run=false archives them. tags: - Lifecycle /v1/memories/expand: post: operationId: expandMemories requestBody: content: application/json: schema: description: Expand a list of memory IDs into full objects. properties: agent_id: description: Optional agent identifier. Silently dropped if empty / non-string. type: string memory_ids: description: Required. memory_ids. items: type: string type: array user_id: description: Required. user_id. minLength: 1 type: string visibility: description: Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined. enum: - agent_only - restricted - workspace type: string workspace_id: description: Optional workspace identifier. Silently dropped if empty / non-string. type: string required: - user_id - memory_ids type: object required: true responses: "200": content: application/json: schema: description: Expanded memory rows for the requested IDs. properties: memories: items: additionalProperties: {} description: Full memory row as emitted by core. properties: access_count: type: number agent_id: type: - string - "null" content: type: string created_at: type: string deleted_at: type: - string - "null" embedding: items: type: number type: array episode_id: type: - string - "null" expired_at: type: - string - "null" id: type: string importance: type: number keywords: type: string last_accessed_at: type: string memory_type: type: string metadata: additionalProperties: {} type: object namespace: type: - string - "null" network: {} observation_subject: type: - string - "null" observed_at: type: string opinion_confidence: type: - number - "null" overview: type: string source_site: type: string source_url: type: string status: enum: - active - needs_clarification type: string summary: type: string trust_score: type: number user_id: type: string visibility: enum: - agent_only - restricted - workspace - null type: - string - "null" workspace_id: type: - string - "null" required: - id - user_id - content - embedding - memory_type - importance - source_site - source_url - status - metadata - keywords - summary - overview - trust_score - observed_at - created_at - last_accessed_at - access_count type: object type: array required: - memories type: object description: Expanded memories array. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Expand a list of memory IDs into full objects. tags: - Memories /v1/memories/health: get: operationId: getMemoryHealth responses: "200": content: application/json: schema: description: Health + runtime config snapshot. properties: config: description: Runtime config snapshot returned by /health + /config. properties: agentic_retrieval_enabled: type: boolean clarification_conflict_threshold: type: number cross_encoder_enabled: type: boolean embedding_model: type: string embedding_provider: type: string entity_graph_enabled: type: boolean hybrid_search_enabled: type: boolean iterative_retrieval_enabled: type: boolean llm_model: type: string llm_provider: type: string max_search_results: type: number repair_loop_enabled: type: boolean retrieval_profile: type: string voyage_document_model: type: string voyage_query_model: type: string required: - retrieval_profile - embedding_provider - embedding_model - voyage_document_model - voyage_query_model - llm_provider - llm_model - clarification_conflict_threshold - max_search_results - hybrid_search_enabled - iterative_retrieval_enabled - entity_graph_enabled - cross_encoder_enabled - agentic_retrieval_enabled - repair_loop_enabled type: object status: enum: - ok type: string required: - status - config type: object description: Status + config snapshot. summary: Subsystem liveness + current runtime config snapshot. tags: - Configuration /v1/memories/ingest: post: description: Full-extraction ingest. The `metadata` field on the body schema is **rejected with 400** on this route — caller metadata is only supported on `POST /v1/memories/ingest/quick` with `skip_extraction=true` and no workspace context. operationId: ingestMemory requestBody: content: application/json: schema: description: Ingest a conversation transcript. User-scoped unless workspace_id + agent_id are both provided. properties: agent_id: description: Optional agent identifier. Silently dropped if empty / non-string. type: string config_override: additionalProperties: anyOf: - type: boolean - type: number - type: string - type: "null" description: "Optional per-request overlay on RuntimeConfig. Keys correspond to RuntimeConfig field names; values must be primitives (boolean / number / string / null). Unknown keys are accepted but surfaced via the X-Atomicmem-Unknown-Override-Keys response header and a server-side warning log — they do not cause a 400. Scope: just this request — no server mutation." type: object content_class: description: "Optional sensitivity class of the supplied content: 'summary' (distilled, hosted-safe), 'redacted' (sensitive spans removed by the caller), or 'raw' (verbatim prompt/response/diff/source). When the deployment runs RAW_CONTENT_POLICY=reject, a verbatim write of 'raw' content — or content with no content_class at all (treated as unknown/raw) — is rejected with 422 raw_content_rejected; on extraction paths the raw transcript is instead withheld from the stored audit episode." enum: - summary - redacted - raw type: string conversation: description: Required. conversation. minLength: 1 type: string metadata: additionalProperties: {} description: Caller-supplied metadata, persisted alongside the memory. Honored ONLY on /v1/memories/ingest/quick with skip_extraction=true and no workspace context — rejected with 400 on every other branch. Reserved keys (RESERVED_METADATA_KEYS in repository-types) are rejected. Max 32 KB UTF-8 serialized. type: object session_id: description: Optional thread/session identifier used to scope ingest, search, and list symmetrically. maxLength: 256 type: string skip_extraction: type: boolean source_site: description: Required. source_site. minLength: 1 type: string source_url: type: string user_id: description: Required. user_id. minLength: 1 type: string visibility: description: Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined. enum: - agent_only - restricted - workspace type: string workspace_id: description: Optional workspace identifier. Silently dropped if empty / non-string. type: string required: - user_id - conversation - source_site type: object required: true responses: "200": content: application/json: schema: description: "Ingest result: extraction counts + stored/updated memory IDs." properties: composites_created: type: number episode_id: type: string facts_extracted: type: number ingest_trace_id: type: string links_created: type: number memories_deleted: type: number memories_skipped: type: number memories_stored: type: number memories_updated: type: number stored_memory_ids: items: type: string type: array updated_memory_ids: items: type: string type: array required: - episode_id - facts_extracted - memories_stored - memories_updated - memories_deleted - memories_skipped - stored_memory_ids - updated_memory_ids - links_created - composites_created type: object description: Ingest result with extracted facts. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Ingest a conversation transcript with full extraction. tags: - Memories /v1/memories/ingest/quick: post: description: Quick or verbatim ingest. The `metadata` field is **honored only** when `skip_extraction=true` and no workspace context (`workspace_id` / `agent_id` / `visibility`) is provided; otherwise rejected with 400. operationId: ingestMemoryQuick requestBody: content: application/json: schema: description: Ingest a conversation transcript. User-scoped unless workspace_id + agent_id are both provided. properties: agent_id: description: Optional agent identifier. Silently dropped if empty / non-string. type: string config_override: additionalProperties: anyOf: - type: boolean - type: number - type: string - type: "null" description: "Optional per-request overlay on RuntimeConfig. Keys correspond to RuntimeConfig field names; values must be primitives (boolean / number / string / null). Unknown keys are accepted but surfaced via the X-Atomicmem-Unknown-Override-Keys response header and a server-side warning log — they do not cause a 400. Scope: just this request — no server mutation." type: object content_class: description: "Optional sensitivity class of the supplied content: 'summary' (distilled, hosted-safe), 'redacted' (sensitive spans removed by the caller), or 'raw' (verbatim prompt/response/diff/source). When the deployment runs RAW_CONTENT_POLICY=reject, a verbatim write of 'raw' content — or content with no content_class at all (treated as unknown/raw) — is rejected with 422 raw_content_rejected; on extraction paths the raw transcript is instead withheld from the stored audit episode." enum: - summary - redacted - raw type: string conversation: description: Required. conversation. minLength: 1 type: string metadata: additionalProperties: {} description: Caller-supplied metadata, persisted alongside the memory. Honored ONLY on /v1/memories/ingest/quick with skip_extraction=true and no workspace context — rejected with 400 on every other branch. Reserved keys (RESERVED_METADATA_KEYS in repository-types) are rejected. Max 32 KB UTF-8 serialized. type: object session_id: description: Optional thread/session identifier used to scope ingest, search, and list symmetrically. maxLength: 256 type: string skip_extraction: type: boolean source_site: description: Required. source_site. minLength: 1 type: string source_url: type: string user_id: description: Required. user_id. minLength: 1 type: string visibility: description: Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined. enum: - agent_only - restricted - workspace type: string workspace_id: description: Optional workspace identifier. Silently dropped if empty / non-string. type: string required: - user_id - conversation - source_site type: object required: true responses: "200": content: application/json: schema: description: "Ingest result: extraction counts + stored/updated memory IDs." properties: composites_created: type: number episode_id: type: string facts_extracted: type: number ingest_trace_id: type: string links_created: type: number memories_deleted: type: number memories_skipped: type: number memories_stored: type: number memories_updated: type: number stored_memory_ids: items: type: string type: array updated_memory_ids: items: type: string type: array required: - episode_id - facts_extracted - memories_stored - memories_updated - memories_deleted - memories_skipped - stored_memory_ids - updated_memory_ids - links_created - composites_created type: object description: Ingest result. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Quick ingest (storeVerbatim when skip_extraction=true). tags: - Memories /v1/memories/lessons: get: operationId: listLessons parameters: - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Active lessons for a user. properties: count: type: number lessons: items: additionalProperties: {} description: Lesson row from the repository. properties: active: type: boolean created_at: type: string embedding: items: type: number type: array id: type: string lesson_type: enum: - injection_blocked - false_memory - contradiction_pattern - user_reported - consensus_violation - trust_violation type: string metadata: additionalProperties: {} type: object pattern: type: string severity: enum: - low - medium - high - critical type: string source_memory_ids: items: type: string type: array source_query: type: - string - "null" user_id: type: string required: - id - user_id - lesson_type - pattern - embedding - source_memory_ids - source_query - severity - active - metadata - created_at type: object type: array required: - lessons - count type: object description: Lessons list. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: List active lessons for a user. tags: - Lessons /v1/memories/lessons/report: post: operationId: reportLesson requestBody: content: application/json: schema: properties: pattern: description: Required. pattern. minLength: 1 type: string severity: {} source_memory_ids: items: type: string type: array user_id: description: Required. user_id. minLength: 1 type: string required: - user_id - pattern type: object required: true responses: "200": content: application/json: schema: description: ID of the newly-reported lesson. properties: lesson_id: type: string required: - lesson_id type: object description: Lesson id. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Report a new lesson. tags: - Lessons /v1/memories/lessons/stats: get: operationId: getLessonStats parameters: - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Aggregate lesson counts by type. properties: by_type: additionalProperties: type: number type: object total_active: type: number required: - total_active - by_type type: object description: Stats. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Lesson statistics for a user. tags: - Lessons /v1/memories/lessons/{id}: delete: operationId: deactivateLesson parameters: - in: path name: id required: true schema: minLength: 1 type: string - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Successful no-payload operation. properties: success: enum: - true type: boolean required: - success type: object description: Success. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Deactivate a lesson by id. tags: - Lessons /v1/memories/list: get: operationId: listMemories parameters: - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: limit required: false schema: type: string - in: query name: offset required: false schema: type: string - in: query name: workspace_id required: false schema: type: string - in: query name: agent_id required: false schema: format: uuid type: string - in: query name: source_site required: false schema: type: string - in: query name: episode_id required: false schema: format: uuid type: string - description: Optional thread/session identifier used to scope ingest, search, and list symmetrically. in: query name: session_id required: false schema: description: Optional thread/session identifier used to scope ingest, search, and list symmetrically. maxLength: 256 type: string responses: "200": content: application/json: schema: description: Paginated memory list. properties: count: type: number memories: items: additionalProperties: {} description: Full memory row as emitted by core. properties: access_count: type: number agent_id: type: - string - "null" content: type: string created_at: type: string deleted_at: type: - string - "null" embedding: items: type: number type: array episode_id: type: - string - "null" expired_at: type: - string - "null" id: type: string importance: type: number keywords: type: string last_accessed_at: type: string memory_type: type: string metadata: additionalProperties: {} type: object namespace: type: - string - "null" network: {} observation_subject: type: - string - "null" observed_at: type: string opinion_confidence: type: - number - "null" overview: type: string source_site: type: string source_url: type: string status: enum: - active - needs_clarification type: string summary: type: string trust_score: type: number user_id: type: string visibility: enum: - agent_only - restricted - workspace - null type: - string - "null" workspace_id: type: - string - "null" required: - id - user_id - content - embedding - memory_type - importance - source_site - source_url - status - metadata - keywords - summary - overview - trust_score - observed_at - created_at - last_accessed_at - access_count type: object type: array required: - memories - count type: object description: Paginated memory list. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: List memories for a user (or workspace). tags: - Memories /v1/memories/reconcile: post: operationId: reconcileDeferred requestBody: content: application/json: schema: properties: user_id: type: string type: object required: false responses: "200": content: application/json: schema: description: Deferred-AUDN reconciliation counters. properties: adds: type: number deletes: type: number duration_ms: type: number errors: type: number noops: type: number processed: type: number resolved: type: number supersedes: type: number updates: type: number required: - processed - resolved - noops - updates - supersedes - deletes - adds - errors - duration_ms type: object description: Reconciliation result. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Reconcile deferred mutations for a user (or all users when user_id is absent). tags: - Lifecycle /v1/memories/reconcile/status: get: operationId: getReconcileStatus parameters: - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: additionalProperties: {} description: Current deferred-AUDN queue state. properties: enabled: type: boolean pending: type: number required: - pending - enabled type: object description: Status payload. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Get deferred-mutation reconciliation status. tags: - Lifecycle /v1/memories/reset-source: post: operationId: resetBySource requestBody: content: application/json: schema: properties: source_site: description: Required. source_site. minLength: 1 type: string user_id: description: Required. user_id. minLength: 1 type: string required: - user_id - source_site type: object required: true responses: "200": content: application/json: schema: description: Reset-by-source deletion counts. properties: deleted_documents: type: number deleted_episodes: type: number deleted_memories: type: number success: enum: - true type: boolean required: - success - deleted_memories - deleted_episodes - deleted_documents type: object description: Reset result. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Delete all memories for a given user + source_site. tags: - Lifecycle /v1/memories/search: post: operationId: searchMemories requestBody: content: application/json: schema: description: Search memories. User-scoped unless workspace_id + agent_id are both provided. properties: agent_id: description: Optional agent identifier. Silently dropped if empty / non-string. type: string agent_scope: description: Agent-scope filter for workspace searches. String literal 'all' | 'self' | 'others' or a concrete agent_id. Array of agent_ids is also accepted. Any other value is silently ignored. example: all oneOf: - type: string - items: type: string type: array as_of: description: ISO-8601 timestamp accepted by temporal search (as_of). Empty string or null means absent; any other non-ISO value is rejected with 400. example: 2026-01-15T12:00:00Z format: date-time type: string config_override: additionalProperties: anyOf: - type: boolean - type: number - type: string - type: "null" description: "Optional per-request overlay on RuntimeConfig. Keys correspond to RuntimeConfig field names; values must be primitives (boolean / number / string / null). Unknown keys are accepted but surfaced via the X-Atomicmem-Unknown-Override-Keys response header and a server-side warning log — they do not cause a 400. Scope: just this request — no server mutation." type: object limit: maximum: 100 minimum: 1 type: integer namespace_scope: type: string query: description: Required. query. minLength: 1 type: string retrieval_mode: enum: - flat - tiered - abstract-aware type: string session_id: description: Optional thread/session identifier used to scope ingest, search, and list symmetrically. maxLength: 256 type: string skip_repair: type: boolean source_site: type: string threshold: description: Optional normalized relevance threshold. Results below this semantic relevance floor are excluded before injection packaging. maximum: 1 minimum: 0 type: number token_budget: maximum: 50000 minimum: 100 type: integer user_id: description: Required. user_id. minLength: 1 type: string visibility: description: Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined. enum: - agent_only - restricted - workspace type: string workspace_id: description: Optional workspace identifier. Silently dropped if empty / non-string. type: string required: - user_id - query type: object required: true responses: "200": content: application/json: schema: description: Search results with injection_text, citations, budget_constrained, and optional traces. properties: budget_constrained: type: boolean citations: items: type: string type: array consensus: properties: filtered_count: type: number original_count: type: number removed_count: type: number removed_memory_ids: items: type: string type: array required: - original_count - filtered_count - removed_count - removed_memory_ids type: object count: type: number deterministic: description: "True only on the LLM-free /search/fast path: no LLM call is made, so the result is replayable given the pinned embedding model in the retrieval receipt. /search reports false because it may run the LLM repair/rerank loop." type: boolean estimated_context_tokens: type: number expand_ids: items: type: string type: array injection_text: type: string lesson_check: properties: highest_severity: type: string matched_count: type: number safe: type: boolean warnings: items: {} type: array required: - safe - warnings - highest_severity - matched_count type: object memories: items: description: Projected memory record in a search result. properties: content: type: string created_at: type: string id: type: string importance: type: - number - "null" metadata: additionalProperties: {} description: Memory metadata persisted on the row, including caller-supplied verbatim metadata (set via /v1/memories/ingest/quick with skip_extraction=true) and core-generated metadata (e.g. cmo_id, memberMemoryIds, headline). Mirrors the shape /v1/memories/list and /v1/memories/:id return. type: object observed_at: description: When the memory was observed/recorded. Part of the retrieval receipt. type: string ranking_score: description: Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range. type: - number - "null" relevance: description: Normalized relevance value used for threshold filtering; clamped to the [0,1] range. type: - number - "null" score: type: - number - "null" semantic_similarity: type: - number - "null" session_id: type: - string - "null" similarity: type: - number - "null" source_site: type: string version_id: description: Owning claim's current_version_id (a claim-version id) for the memory, enabling a client to pin the exact retrieved version as a replay fixture. null when the memory has no claim version (e.g. workspace-pool rows). type: - string - "null" required: - id - content type: object type: array observability: description: Retrieval pipeline trace summaries. properties: assembly: properties: blocks: items: type: string type: array final_ids: items: type: string type: array final_token_cost: type: number primary_evidence_position: type: - number - "null" token_budget: type: - number - "null" required: - final_ids - final_token_cost - token_budget - primary_evidence_position - blocks type: object packaging: properties: date_count: type: number dropped_ids: items: type: string type: array episode_count: type: number evidence_roles: additionalProperties: enum: - primary - supporting - historical - contextual type: string type: object has_conflict_block: type: boolean has_current_marker: type: boolean included_ids: items: type: string type: array package_type: enum: - subject-pack - timeline-pack - tiered type: string token_cost: type: number required: - package_type - included_ids - dropped_ids - evidence_roles - episode_count - date_count - has_current_marker - has_conflict_block - token_cost type: object retrieval: properties: candidate_count: type: number candidate_ids: items: type: string type: array filter_decisions: description: Per-candidate threshold decisions emitted only when retrieval tracing is enabled. Entries include per-result source_site, source_kind, and namespace for debugging disclosure scope. items: properties: decision: enum: - kept - filtered type: string id: type: string namespace: type: - string - "null" ranking_score: description: Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range. type: number reason: type: string relevance: description: Normalized relevance value used for threshold filtering; clamped to the [0,1] range. type: number semantic_similarity: type: number source_kind: enum: - integration - local type: string source_site: type: string threshold: type: - number - "null" required: - id - source_site - source_kind - namespace - semantic_similarity - ranking_score - relevance - threshold - decision - reason type: object type: array filtered_candidate_ids: items: type: string type: array query_text: type: string relevance_filter_reason: type: string relevance_filter_source: type: string relevance_threshold: type: - number - "null" skip_repair: type: boolean stage_count: type: number stage_names: items: type: string type: array trace_id: type: string required: - candidate_ids - candidate_count - query_text - skip_repair type: object type: object retrieval: description: Audit-grade retrieval receipt. properties: candidate_ids: description: Returned memory ids in ranked order. items: type: string type: array embedding_dimensions: type: number embedding_model: type: string embedding_model_version: description: Embedding model version. No supported provider exposes a separate immutable version string, so this is the resolved model id — the most precise model identity the provider reports, never a fabricated value. type: string embedding_provider: type: string query_text: type: string trace_id: type: string required: - embedding_provider - embedding_model - embedding_model_version - embedding_dimensions - query_text - candidate_ids - trace_id type: object retrieval_mode: enum: - flat - tiered - abstract-aware type: string scope: anyOf: - properties: kind: enum: - user type: string user_id: type: string required: - kind - user_id type: object - properties: agent_id: type: string agent_scope: {} kind: enum: - workspace type: string user_id: type: string workspace_id: type: string required: - kind - user_id - workspace_id - agent_id type: object description: "Echoed scope: user-scoped or workspace-scoped." specialist_answer: type: string tier_assignments: items: properties: estimated_tokens: type: number memory_id: type: string tier: type: string required: - memory_id - tier - estimated_tokens type: object type: array required: - count - retrieval_mode - scope - retrieval - memories - budget_constrained type: object description: Search results with injection_text and citations. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Full semantic search with optional temporal / retrieval-mode / token-budget controls. tags: - Memories /v1/memories/search/fast: post: operationId: searchMemoriesFast requestBody: content: application/json: schema: description: Search memories. User-scoped unless workspace_id + agent_id are both provided. properties: agent_id: description: Optional agent identifier. Silently dropped if empty / non-string. type: string agent_scope: description: Agent-scope filter for workspace searches. String literal 'all' | 'self' | 'others' or a concrete agent_id. Array of agent_ids is also accepted. Any other value is silently ignored. example: all oneOf: - type: string - items: type: string type: array as_of: description: ISO-8601 timestamp accepted by temporal search (as_of). Empty string or null means absent; any other non-ISO value is rejected with 400. example: 2026-01-15T12:00:00Z format: date-time type: string config_override: additionalProperties: anyOf: - type: boolean - type: number - type: string - type: "null" description: "Optional per-request overlay on RuntimeConfig. Keys correspond to RuntimeConfig field names; values must be primitives (boolean / number / string / null). Unknown keys are accepted but surfaced via the X-Atomicmem-Unknown-Override-Keys response header and a server-side warning log — they do not cause a 400. Scope: just this request — no server mutation." type: object limit: maximum: 100 minimum: 1 type: integer namespace_scope: type: string query: description: Required. query. minLength: 1 type: string retrieval_mode: enum: - flat - tiered - abstract-aware type: string session_id: description: Optional thread/session identifier used to scope ingest, search, and list symmetrically. maxLength: 256 type: string skip_repair: type: boolean source_site: type: string threshold: description: Optional normalized relevance threshold. Results below this semantic relevance floor are excluded before injection packaging. maximum: 1 minimum: 0 type: number token_budget: maximum: 50000 minimum: 100 type: integer user_id: description: Required. user_id. minLength: 1 type: string visibility: description: Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined. enum: - agent_only - restricted - workspace type: string workspace_id: description: Optional workspace identifier. Silently dropped if empty / non-string. type: string required: - user_id - query type: object required: true responses: "200": content: application/json: schema: description: Search results with injection_text, citations, budget_constrained, and optional traces. properties: budget_constrained: type: boolean citations: items: type: string type: array consensus: properties: filtered_count: type: number original_count: type: number removed_count: type: number removed_memory_ids: items: type: string type: array required: - original_count - filtered_count - removed_count - removed_memory_ids type: object count: type: number deterministic: description: "True only on the LLM-free /search/fast path: no LLM call is made, so the result is replayable given the pinned embedding model in the retrieval receipt. /search reports false because it may run the LLM repair/rerank loop." type: boolean estimated_context_tokens: type: number expand_ids: items: type: string type: array injection_text: type: string lesson_check: properties: highest_severity: type: string matched_count: type: number safe: type: boolean warnings: items: {} type: array required: - safe - warnings - highest_severity - matched_count type: object memories: items: description: Projected memory record in a search result. properties: content: type: string created_at: type: string id: type: string importance: type: - number - "null" metadata: additionalProperties: {} description: Memory metadata persisted on the row, including caller-supplied verbatim metadata (set via /v1/memories/ingest/quick with skip_extraction=true) and core-generated metadata (e.g. cmo_id, memberMemoryIds, headline). Mirrors the shape /v1/memories/list and /v1/memories/:id return. type: object observed_at: description: When the memory was observed/recorded. Part of the retrieval receipt. type: string ranking_score: description: Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range. type: - number - "null" relevance: description: Normalized relevance value used for threshold filtering; clamped to the [0,1] range. type: - number - "null" score: type: - number - "null" semantic_similarity: type: - number - "null" session_id: type: - string - "null" similarity: type: - number - "null" source_site: type: string version_id: description: Owning claim's current_version_id (a claim-version id) for the memory, enabling a client to pin the exact retrieved version as a replay fixture. null when the memory has no claim version (e.g. workspace-pool rows). type: - string - "null" required: - id - content type: object type: array observability: description: Retrieval pipeline trace summaries. properties: assembly: properties: blocks: items: type: string type: array final_ids: items: type: string type: array final_token_cost: type: number primary_evidence_position: type: - number - "null" token_budget: type: - number - "null" required: - final_ids - final_token_cost - token_budget - primary_evidence_position - blocks type: object packaging: properties: date_count: type: number dropped_ids: items: type: string type: array episode_count: type: number evidence_roles: additionalProperties: enum: - primary - supporting - historical - contextual type: string type: object has_conflict_block: type: boolean has_current_marker: type: boolean included_ids: items: type: string type: array package_type: enum: - subject-pack - timeline-pack - tiered type: string token_cost: type: number required: - package_type - included_ids - dropped_ids - evidence_roles - episode_count - date_count - has_current_marker - has_conflict_block - token_cost type: object retrieval: properties: candidate_count: type: number candidate_ids: items: type: string type: array filter_decisions: description: Per-candidate threshold decisions emitted only when retrieval tracing is enabled. Entries include per-result source_site, source_kind, and namespace for debugging disclosure scope. items: properties: decision: enum: - kept - filtered type: string id: type: string namespace: type: - string - "null" ranking_score: description: Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range. type: number reason: type: string relevance: description: Normalized relevance value used for threshold filtering; clamped to the [0,1] range. type: number semantic_similarity: type: number source_kind: enum: - integration - local type: string source_site: type: string threshold: type: - number - "null" required: - id - source_site - source_kind - namespace - semantic_similarity - ranking_score - relevance - threshold - decision - reason type: object type: array filtered_candidate_ids: items: type: string type: array query_text: type: string relevance_filter_reason: type: string relevance_filter_source: type: string relevance_threshold: type: - number - "null" skip_repair: type: boolean stage_count: type: number stage_names: items: type: string type: array trace_id: type: string required: - candidate_ids - candidate_count - query_text - skip_repair type: object type: object retrieval: description: Audit-grade retrieval receipt. properties: candidate_ids: description: Returned memory ids in ranked order. items: type: string type: array embedding_dimensions: type: number embedding_model: type: string embedding_model_version: description: Embedding model version. No supported provider exposes a separate immutable version string, so this is the resolved model id — the most precise model identity the provider reports, never a fabricated value. type: string embedding_provider: type: string query_text: type: string trace_id: type: string required: - embedding_provider - embedding_model - embedding_model_version - embedding_dimensions - query_text - candidate_ids - trace_id type: object retrieval_mode: enum: - flat - tiered - abstract-aware type: string scope: anyOf: - properties: kind: enum: - user type: string user_id: type: string required: - kind - user_id type: object - properties: agent_id: type: string agent_scope: {} kind: enum: - workspace type: string user_id: type: string workspace_id: type: string required: - kind - user_id - workspace_id - agent_id type: object description: "Echoed scope: user-scoped or workspace-scoped." specialist_answer: type: string tier_assignments: items: properties: estimated_tokens: type: number memory_id: type: string tier: type: string required: - memory_id - tier - estimated_tokens type: object type: array required: - count - retrieval_mode - scope - retrieval - memories - budget_constrained type: object description: Search results. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Latency-optimized search (skips LLM repair loop). ~88% lower latency than /search. tags: - Memories /v1/memories/stats: get: operationId: getStats parameters: - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Aggregate memory stats for a user. properties: avg_importance: type: number count: type: number source_distribution: additionalProperties: type: number type: object required: - count - avg_importance - source_distribution type: object description: Stats payload. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Aggregate memory statistics for a user. tags: - Memories /v1/memories/{id}: delete: operationId: deleteMemory parameters: - in: path name: id required: true schema: format: uuid type: string - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: workspace_id required: false schema: type: string - in: query name: agent_id required: false schema: format: uuid type: string responses: "200": content: application/json: schema: description: Successful no-payload operation. properties: success: enum: - true type: boolean required: - success type: object description: Deletion success. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Memory not found "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Delete a single memory by UUID. tags: - Memories get: operationId: getMemory parameters: - in: path name: id required: true schema: format: uuid type: string - in: query name: user_id required: true schema: minLength: 1 type: string - in: query name: workspace_id required: false schema: type: string - in: query name: agent_id required: false schema: format: uuid type: string responses: "200": content: application/json: schema: additionalProperties: {} description: Full memory row as emitted by core. properties: access_count: type: number agent_id: type: - string - "null" content: type: string created_at: type: string deleted_at: type: - string - "null" embedding: items: type: number type: array episode_id: type: - string - "null" expired_at: type: - string - "null" id: type: string importance: type: number keywords: type: string last_accessed_at: type: string memory_type: type: string metadata: additionalProperties: {} type: object namespace: type: - string - "null" network: {} observation_subject: type: - string - "null" observed_at: type: string opinion_confidence: type: - number - "null" overview: type: string source_site: type: string source_url: type: string status: enum: - active - needs_clarification type: string summary: type: string trust_score: type: number user_id: type: string visibility: enum: - agent_only - restricted - workspace - null type: - string - "null" workspace_id: type: - string - "null" required: - id - user_id - content - embedding - memory_type - importance - source_site - source_url - status - metadata - keywords - summary - overview - trust_score - observed_at - created_at - last_accessed_at - access_count type: object description: Memory object. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Memory not found "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Fetch a single memory by UUID. tags: - Memories /v1/memories/{id}/audit: get: operationId: getMemoryAuditTrail parameters: - in: path name: id required: true schema: format: uuid type: string - in: query name: user_id required: true schema: minLength: 1 type: string responses: "200": content: application/json: schema: description: Full version trail for a single memory. properties: memory_id: type: string trail: items: description: Single entry in a memory's audit trail. properties: actor_model: type: - string - "null" claim_id: type: string content: type: string content_hash: description: Stable, content-addressable SHA-256 (hex) of this version's content computed as sha256("radar-claim-version-content:v1\n" + content). Deterministic — identical content yields the same hash — so a downstream caller audit chain can anchor to a specific claim version. Not a chain hash. type: string contradiction_confidence: type: - number - "null" memory_id: type: - string - "null" mutation_reason: type: - string - "null" mutation_type: enum: - add - update - supersede - delete - clarify - null type: - string - "null" previous_version_id: type: - string - "null" superseded_by_version_id: type: - string - "null" valid_from: type: string valid_to: type: - string - "null" version_id: type: string required: - version_id - claim_id - content - content_hash - mutation_type - mutation_reason - actor_model - contradiction_confidence - previous_version_id - superseded_by_version_id - valid_from - valid_to - memory_id type: object type: array version_count: type: number required: - memory_id - trail - version_count type: object description: Audit trail. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Per-memory version history. tags: - Audit /v1/storage/artifacts: post: description: 'Pointer mode sends a JSON body with `mode: "pointer"` plus a caller-supplied `uri`; the server stores the reference but NEVER fetches the URI. Managed mode sends the raw bytes with `?mode=managed[&disclose_content_hash=true]` and an optional `X-AtomicMemory-Metadata` base64-JSON header. Filecoin direct managed uploads return 501 in v1.' operationId: putStorageArtifact requestBody: content: application/json: schema: description: Discriminated union over put-artifact mode. oneOf: - additionalProperties: false description: Pointer-mode artifact registration body. The server stores the URI as a reference; it NEVER fetches the URI itself. properties: content_hash: minLength: 1 type: string content_type: minLength: 1 type: string metadata: additionalProperties: anyOf: - type: string - type: number - type: boolean description: Caller-supplied metadata. Decoded JSON must be ≤4 KiB; encoded header value must be ≤8 KiB when sent via `X-AtomicMemory-Metadata`. type: object mode: enum: - pointer type: string size_bytes: minimum: 0 type: integer uri: minLength: 1 type: string required: - mode - uri - content_type type: object - additionalProperties: false description: Managed-mode marker. The route uses query params for the managed-mode contract; the body is raw bytes, not JSON. Included in the discriminated union so a managed-mode JSON body (caller mistake) parses cleanly and is rejected at the route layer. properties: mode: enum: - managed type: string required: - mode type: object required: true responses: "201": content: application/json: schema: additionalProperties: false description: Public metadata projection of a `storage_artifacts` row. `content_hash` is the plaintext SHA-256 of caller bytes; the internal `stored_hash` column is NEVER surfaced on the wire. properties: artifact_id: format: uuid type: string content_encoding: enum: - identity - aes_gcm type: string content_hash: type: string content_type: type: - string - "null" created_at: type: string identifiers: additionalProperties: type: string description: Provider-native identifiers (CID, etc.); allowlisted per provider. type: object lifecycle: additionalProperties: false description: Provider-agnostic summary of availability + delete-semantics. Both fields are optional so a row whose lifecycle is not yet known to the API surface validates cleanly. properties: availability: description: Coarse availability category for the backend. enum: - immediate - delayed - scheduled - best_effort type: string deleteSemantics: description: What the backend does on delete. `delete` issues provider removal; `unpin` removes the AtomicMemory reference only; `tombstone` stops managing without provider removal (typical for decentralized providers); `provider_retained` is reserved. enum: - delete - unpin - tombstone - provider_retained type: string type: object metadata: additionalProperties: anyOf: - type: string - type: number - type: boolean description: Caller-supplied metadata. Decoded JSON must be ≤4 KiB; encoded header value must be ≤8 KiB when sent via `X-AtomicMemory-Metadata`. type: object mode: enum: - pointer - managed type: string provider: type: string provider_details: additionalProperties: {} description: Allowlisted provider-specific public state. type: object replication: additionalProperties: false description: Optional replication state for eventual storage providers. properties: confirmedCopies: minimum: 0 type: integer desiredCopies: minimum: 0 type: integer type: object retrieval: additionalProperties: false description: Optional retrieval-readiness state. properties: lastCheckedAt: type: string status: enum: - not_checked - retrievable - not_retrievable - unsupported type: string type: object size_bytes: minimum: 0 type: - integer - "null" status: enum: - stored - pending - available - unavailable - deleting - deleted - delete_failed - failed type: string updated_at: type: string uri: type: - string - "null" verification: additionalProperties: false description: Optional verification state (provider proofs). properties: lastVerifiedAt: type: string providerProofStatus: enum: - pending - verified - failed - unsupported type: string type: object required: - artifact_id - provider - mode - uri - status - size_bytes - content_type - content_encoding - identifiers - lifecycle - metadata - created_at - updated_at type: object description: Artifact created. "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "411": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Content-Length is required for managed uploads. "413": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Managed upload body exceeds the configured cap. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "501": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Direct Filecoin managed upload is not supported in v1. "503": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Managed storage is disabled for this deployment. summary: Register a pointer artifact or upload a managed artifact. tags: - Storage /v1/storage/artifacts/{id}: delete: description: Reference-aware delete. Default `policy=artifact_only` returns 409 `artifact_in_use` if any active document references the artifact; `policy=with_documents` cascades a soft-delete to those documents first. No `force` parameter is supported. operationId: deleteStorageArtifact parameters: - in: path name: id required: true schema: format: uuid type: string - description: Delete behaviour when documents reference the artifact. `artifact_only` (default) returns 409 `artifact_in_use` if any non-deleted documents reference it. `with_documents` cascades a soft-delete to those documents first. in: query name: policy required: false schema: description: Delete behaviour when documents reference the artifact. `artifact_only` (default) returns 409 `artifact_in_use` if any non-deleted documents reference it. `with_documents` cascades a soft-delete to those documents first. enum: - artifact_only - with_documents type: string responses: "200": content: application/json: schema: additionalProperties: false description: Result of `DELETE /v1/storage/artifacts/:id`. properties: artifact_id: format: uuid type: string cascaded_document_ids: items: format: uuid type: string type: array status: enum: - deleted - delete_failed type: string required: - artifact_id - status type: object description: Artifact deleted (or delete failed at the backend). "400": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Input validation error "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Artifact not found. "409": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: "Artifact is referenced by active documents (`error_code: artifact_in_use`) OR another caller holds an active delete claim and this caller never ran the delete (`error_code: delete_in_flight`, `retryable: true`)." "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Soft-delete an artifact (optionally cascading documents). tags: - Storage get: operationId: getStorageArtifact parameters: - in: path name: id required: true schema: format: uuid type: string responses: "200": content: application/json: schema: additionalProperties: false description: Public metadata projection of a `storage_artifacts` row. `content_hash` is the plaintext SHA-256 of caller bytes; the internal `stored_hash` column is NEVER surfaced on the wire. properties: artifact_id: format: uuid type: string content_encoding: enum: - identity - aes_gcm type: string content_hash: type: string content_type: type: - string - "null" created_at: type: string identifiers: additionalProperties: type: string description: Provider-native identifiers (CID, etc.); allowlisted per provider. type: object lifecycle: additionalProperties: false description: Provider-agnostic summary of availability + delete-semantics. Both fields are optional so a row whose lifecycle is not yet known to the API surface validates cleanly. properties: availability: description: Coarse availability category for the backend. enum: - immediate - delayed - scheduled - best_effort type: string deleteSemantics: description: What the backend does on delete. `delete` issues provider removal; `unpin` removes the AtomicMemory reference only; `tombstone` stops managing without provider removal (typical for decentralized providers); `provider_retained` is reserved. enum: - delete - unpin - tombstone - provider_retained type: string type: object metadata: additionalProperties: anyOf: - type: string - type: number - type: boolean description: Caller-supplied metadata. Decoded JSON must be ≤4 KiB; encoded header value must be ≤8 KiB when sent via `X-AtomicMemory-Metadata`. type: object mode: enum: - pointer - managed type: string provider: type: string provider_details: additionalProperties: {} description: Allowlisted provider-specific public state. type: object replication: additionalProperties: false description: Optional replication state for eventual storage providers. properties: confirmedCopies: minimum: 0 type: integer desiredCopies: minimum: 0 type: integer type: object retrieval: additionalProperties: false description: Optional retrieval-readiness state. properties: lastCheckedAt: type: string status: enum: - not_checked - retrievable - not_retrievable - unsupported type: string type: object size_bytes: minimum: 0 type: - integer - "null" status: enum: - stored - pending - available - unavailable - deleting - deleted - delete_failed - failed type: string updated_at: type: string uri: type: - string - "null" verification: additionalProperties: false description: Optional verification state (provider proofs). properties: lastVerifiedAt: type: string providerProofStatus: enum: - pending - verified - failed - unsupported type: string type: object required: - artifact_id - provider - mode - uri - status - size_bytes - content_type - content_encoding - identifiers - lifecycle - metadata - created_at - updated_at type: object description: Artifact metadata. "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Artifact not found. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Read an artifact metadata projection. tags: - Storage /v1/storage/artifacts/{id}/content: get: description: Returns the artifact bytes for managed-mode artifacts. Pointer-mode artifacts return 409 `pointer_content_not_managed` — the server never proxies pointer content. operationId: getStorageArtifactContent parameters: - in: path name: id required: true schema: format: uuid type: string responses: "200": description: Raw bytes. "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Artifact not found. "409": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Pointer-mode artifact; fetch the URI directly. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "503": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Managed storage is disabled for this deployment. summary: Read the raw bytes for a managed artifact. tags: - Storage /v1/storage/artifacts/{id}/verify: post: description: "Pointer-mode artifacts always return `kind: 'unsupported'` — the server never fetches the registered URI." operationId: verifyStorageArtifact parameters: - in: path name: id required: true schema: format: uuid type: string responses: "200": content: application/json: schema: additionalProperties: false description: "Result of `POST /v1/storage/artifacts/:id/verify`. Pointer-mode artifacts always report `kind: 'unsupported'` because the server never fetches the registered URI." properties: artifact_id: format: uuid type: string details: additionalProperties: {} type: object kind: enum: - verified - failed - unsupported type: string reason: type: string required: - artifact_id - kind type: object description: Verification result. "404": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Artifact not found. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error summary: Run the backend's verification (head-probe in v1). tags: - Storage /v1/storage/capabilities: get: description: Public preflight surface for the storage API. Clients call this before attempting a managed-mode artifact upload. The response describes what the direct `/v1/storage/artifacts/*` API supports for the active backend — Filecoin direct managed upload is not yet supported in v1, so every capability flag reports `false` for Filecoin here. Filecoin still has full feature support through document ingestion (see `/v1/documents/limits`). operationId: getStorageCapabilities responses: "200": content: application/json: schema: additionalProperties: false description: "Capability snapshot for the direct storage API (`/v1/storage/artifacts/*`). Composition-time projection; no per-user state. Document ingestion's own capability surface lives at `/v1/documents/limits` and may report different flags (e.g. Filecoin reports `supportsContentHash: true` through documents but `false` here in v1 because direct managed Filecoin upload is not yet supported)." properties: addressing: items: description: How the backend addresses stored bytes. enum: - location - content - provider_native type: string type: array availabilityModel: description: Coarse availability category for the backend. enum: - immediate - delayed - scheduled - best_effort type: string consistency: description: When bytes become retrievable after put. enum: - immediate - eventual type: string deleteSemantics: items: description: What the backend does on delete. `delete` issues provider removal; `unpin` removes the AtomicMemory reference only; `tombstone` stops managing without provider removal (typical for decentralized providers); `provider_retained` is reserved. enum: - delete - unpin - tombstone - provider_retained type: string type: array maxUploadBytes: exclusiveMinimum: 0 type: integer minUploadBytes: minimum: 0 type: integer provider: type: string supportedBundleFormats: items: type: string type: array supportsBundles: type: boolean supportsContentAddressedUri: type: boolean supportsContentHash: type: boolean supportsDelete: type: boolean supportsDirectUpload: type: boolean supportsProviderProofs: type: boolean supportsRangeRead: type: boolean supportsReplication: type: boolean supportsRetrievalStatus: type: boolean supportsTombstone: type: boolean supportsVerification: type: boolean required: - provider - addressing - consistency - supportsDirectUpload - supportsRangeRead - supportsDelete - supportsTombstone - supportsBundles - supportedBundleFormats - supportsVerification - supportsProviderProofs - supportsReplication - supportsRetrievalStatus - supportsContentHash - supportsContentAddressedUri - deleteSemantics - availabilityModel type: object description: Capability snapshot for the direct storage API. "500": content: application/json: schema: description: Standard error envelope. 400 for input validation errors, 500 for uncaught exceptions. example: error: user_id is required properties: error: type: string required: - error type: object description: Internal server error "502": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx). "503": content: application/json: schema: description: Upstream AI provider failure envelope (502 / 503). example: details: "Incorrect API key provided: [REDACTED_API_KEY]." error: Upstream provider authentication failed error_code: upstream_provider_auth_failed message: The configured AI provider rejected the request credentials. Check the provider API key and account access. provider_status: 401 retryable: false properties: details: type: string error: type: string error_code: enum: - upstream_provider_auth_failed - upstream_provider_rate_limited - upstream_provider_quota_exceeded - upstream_provider_error type: string message: type: string provider_status: type: integer retryable: type: boolean required: - error_code - error - message - provider_status - retryable - details type: object description: Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`. summary: Read the direct storage API capability snapshot. tags: - Storage security: - bearerAuth: [] servers: - description: Local development server url: http://localhost:17350 webhooks: {}