{ "openapi": "3.0.0", "paths": { "/v1/memories": { "post": { "description": "Writes one or more memories to a scope and returns them already searchable, together with a per-item receipt reporting whether each input was created or deduplicated.", "operationId": "createMemories", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoriesDto" } } } }, "responses": { "201": { "description": "Memories are committed and searchable. The receipt reports every input outcome without exposing ingestion internals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoriesResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create explicit memories in the synchronous memory lane.", "tags": ["Memories"] }, "get": { "description": "Returns a cursor-paginated page of memories for one scope, newest first, plus the total across all pages.", "operationId": "listMemories", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTMwVDE0OjAwOjAwLjAwMFoiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9", "type": "string" } }, { "name": "scopeType", "required": false, "in": "query", "schema": { "example": "user", "type": "string" } }, { "name": "scopeId", "required": false, "in": "query", "schema": { "example": "alice", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "description": "Deprecated shorthand alias for scope filtering.", "deprecated": true, "schema": { "example": "user:alice", "type": "string" } } ], "responses": { "200": { "description": "A page of memories for the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMemoriesResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "List stored memories within a required scope or legacy containerTag.", "tags": ["Memories"] } }, "/v1/memories/{memoryId}": { "get": { "description": "Returns one memory. The scope it belongs to must be supplied, either as scopeType and scopeId or as the deprecated containerTag.", "operationId": "getMemory", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTMwVDE0OjAwOjAwLjAwMFoiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9", "type": "string" } }, { "name": "scopeType", "required": false, "in": "query", "schema": { "example": "user", "type": "string" } }, { "name": "scopeId", "required": false, "in": "query", "schema": { "example": "alice", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "description": "Deprecated shorthand alias for scope filtering.", "deprecated": true, "schema": { "example": "user:alice", "type": "string" } } ], "responses": { "200": { "description": "The requested memory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Fetch a single memory by ID.", "tags": ["Memories"] }, "patch": { "description": "Applies a partial update and re-embeds the memory so retrieval reflects the new content immediately.", "operationId": "updateMemory", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTMwVDE0OjAwOjAwLjAwMFoiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9", "type": "string" } }, { "name": "scopeType", "required": false, "in": "query", "schema": { "example": "user", "type": "string" } }, { "name": "scopeId", "required": false, "in": "query", "schema": { "example": "alice", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "description": "Deprecated shorthand alias for scope filtering.", "deprecated": true, "schema": { "example": "user:alice", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryDto" } } } }, "responses": { "200": { "description": "The updated memory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a stored memory and refresh its embedding.", "tags": ["Memories"] }, "delete": { "description": "Removes a memory from retrieval. Deployments running complete cascading deletion, and privileged memories anywhere, also return an erasure receipt itemising what was purged.", "operationId": "deleteMemory", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "permanent", "required": true, "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTMwVDE0OjAwOjAwLjAwMFoiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9", "type": "string" } }, { "name": "scopeType", "required": false, "in": "query", "schema": { "example": "user", "type": "string" } }, { "name": "scopeId", "required": false, "in": "query", "schema": { "example": "alice", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "description": "Deprecated shorthand alias for scope filtering.", "deprecated": true, "schema": { "example": "user:alice", "type": "string" } } ], "responses": { "200": { "description": "The memory is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemoryResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete a memory — a recoverable soft delete by default, or a permanent delete when permanent=true.", "tags": ["Memories"] } }, "/v1/memories/{memoryId}/protection": { "patch": { "description": "Switches a memory between the standard and privileged mutation policies. Privileged memories can only be changed by a credential holding the protected-memory scope.", "operationId": "updateMemoryProtection", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryProtectionDto" } } } }, "responses": { "200": { "description": "The memory with its new mutation policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Protect or unprotect a memory using a privileged credential.", "tags": ["Memories"] } }, "/v1/memories/{memoryId}/restore": { "post": { "description": "Reinstates a memory from its encrypted deletion archive. Only works while the receipt is still restorable.", "operationId": "restoreMemory", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The memory is restored and searchable again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreMemoryResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "409": { "description": "The resource is in a state that conflicts with this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Restore a memory during its recoverable deletion window.", "tags": ["Memories"] } }, "/v1/documents": { "post": { "description": "Queues a document for background extraction and returns the stored document plus the job to poll. Re-uploading the same customId returns the existing document instead of duplicating it.", "operationId": "createDocument", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentDto" } } } }, "responses": { "201": { "description": "The document is stored and its ingestion job is queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "413": { "description": "The submitted content exceeds the ingestion size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create or update a raw source document in the async ingestion lane.", "tags": ["Documents"] }, "get": { "description": "Returns a cursor-paginated page of documents for one scope, most recently updated first.", "operationId": "listDocuments", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "example": 25, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTMwVDE0OjAwOjAwLjAwMFoiLCJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9", "type": "string" } }, { "name": "scopeType", "required": false, "in": "query", "schema": { "example": "user", "type": "string" } }, { "name": "scopeId", "required": false, "in": "query", "schema": { "example": "alice", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "description": "Deprecated shorthand alias for scope filtering.", "deprecated": true, "schema": { "example": "user:alice", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": ["queued", "processing", "completed", "failed"] } } ], "responses": { "200": { "description": "A page of documents for the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "List stored documents within a required scope or legacy containerTag.", "tags": ["Documents"] } }, "/v1/documents/batch": { "post": { "description": "Submits many documents in one call. Each entry succeeds or fails on its own, and the results array mirrors the submission order.", "operationId": "createDocumentsBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentsBatchDto" } } } }, "responses": { "201": { "description": "Per-document outcomes, in submission order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentsBatchResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "413": { "description": "The submitted content exceeds the ingestion size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create or update up to 50 documents while isolating per-document ingestion failures.", "tags": ["Documents"] } }, "/v1/documents/{documentId}": { "get": { "description": "Returns one document with its full content and the state of its most recent ingestion job.", "operationId": "getDocument", "parameters": [ { "name": "documentId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRecordDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Fetch a single document by ID.", "tags": ["Documents"] }, "patch": { "description": "Applies a partial update. Changing the content, or passing reprocess, queues a fresh ingestion job which is returned alongside the document.", "operationId": "updateDocument", "parameters": [ { "name": "documentId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentDto" } } } }, "responses": { "200": { "description": "The updated document, plus the requeued job when one was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "409": { "description": "The resource is in a state that conflicts with this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "413": { "description": "The submitted content exceeds the ingestion size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a document and optionally requeue processing.", "tags": ["Documents"] }, "delete": { "description": "Soft-deletes the document, withdraws every memory derived from it, and fails any ingestion job still in flight.", "operationId": "deleteDocument", "parameters": [ { "name": "documentId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document is deleted and its derived memories withdrawn.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDocumentResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "409": { "description": "The resource is in a state that conflicts with this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete a document and hide its derived memories.", "tags": ["Documents"] } }, "/v1/jobs": { "get": { "description": "Resolves up to 50 job ids at once. Ids that do not belong to the workspace are omitted from the response rather than raising an error.", "operationId": "listJobs", "parameters": [ { "name": "ids", "required": true, "in": "query", "description": "Comma-separated list of job UUIDs. Max 50.", "schema": {} } ], "responses": { "200": { "description": "The jobs that resolved, in the order their ids were supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Batch lookup of multiple ingestion jobs in one round trip.", "tags": ["Jobs"] } }, "/v1/jobs/{jobId}": { "get": { "description": "Returns the current state of one ingestion job. Pass wait to block until the job reaches a terminal state, and If-None-Match to get a bodyless 304 while nothing has changed.", "operationId": "getJob", "parameters": [ { "name": "jobId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "if-none-match", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "wait", "required": false, "in": "query", "description": "Long-poll up to N seconds (max 30) for the job to reach a terminal state (completed | failed) or for its updatedAt to advance past the value implied by If-None-Match.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The current state of the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRecordDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "304": { "description": "The job has not changed since the supplied If-None-Match ETag. No response body.", "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get the status of an async document ingestion job. Supports ETag, If-None-Match, and optional ?wait= long-polling.", "tags": ["Jobs"] } }, "/v1/search": { "post": { "description": "Runs vector, keyword, and fact retrieval in parallel, fuses the results, and returns ranked hits already split into positive preferences and hard constraints. Responds 201 because the query travels in the request body.", "operationId": "searchMemories", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequestDto" } } } }, "responses": { "201": { "description": "Ranked retrieval results with the routing and latency trace for the query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "402": { "description": "The requested capability is not included in the workspace plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Search across memories and documents with hybrid retrieval.", "tags": ["Search"] } }, "/v1/profile": { "post": { "description": "Assembles the stable facts, recent memories, and hard constraints for one scope into a block you can drop straight into a system prompt. Responds 201 because the scope travels in the request body.", "operationId": "getMemoryProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRequestDto" } } } }, "responses": { "201": { "description": "The assembled profile for the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Return a prompt-ready memory profile for a single scope.", "tags": ["Profile"] } }, "/v1/public/newsletter/subscriptions": { "post": { "description": "Accepts an email address and sends it a confirmation link. The response is identical for new, existing, and rejected addresses so subscribers cannot be enumerated.", "operationId": "subscribeToNewsletter", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeNewsletterDto" } } } }, "responses": { "202": { "description": "The signup was accepted and a confirmation email is on its way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscriptionResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [], "summary": "Request a newsletter subscription confirmation.", "tags": ["Newsletter"] } }, "/v1/public/newsletter/confirm": { "get": { "description": "Consumes the token from the confirmation email and redirects to the marketing site with the outcome in a status query parameter. Never returns a body.", "operationId": "confirmNewsletterSubscription", "parameters": [ { "name": "token", "required": false, "in": "query", "description": "Single-use token from the confirmation email. A missing or unknown token redirects with status=invalid.", "schema": {} } ], "responses": { "303": { "description": "Redirect to the marketing site. The Location URL carries status=confirmed, status=invalid, or status=unavailable. No response body.", "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [], "summary": "Confirm a newsletter subscription from an emailed link.", "tags": ["Newsletter"] } }, "/v1/media/youtube/estimate": { "post": { "description": "Resolves a YouTube URL to its video metadata and reports whether its duration fits the workspace quota, without queueing anything. Responds 201 because the URL travels in the request body.", "operationId": "estimateYouTubeIngestion", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateYouTubeDto" } } } }, "responses": { "201": { "description": "Video metadata plus the quota this ingestion would consume.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeEstimateResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "The request is well-formed but the referenced media cannot be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "The capability is not enabled for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Validate a public YouTube URL and check video quota.", "tags": ["YouTube"] } }, "/v1/media/youtube": { "post": { "description": "Reserves quota and queues a YouTube video for transcript, or transcript and visual, ingestion. An identical non-failed ingestion is returned as-is rather than queued again.", "operationId": "createYouTubeIngestion", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateYouTubeIngestionDto" } } } }, "responses": { "201": { "description": "The ingestion record, with the job id to poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeIngestionResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "409": { "description": "The resource is in a state that conflicts with this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "The request is well-formed but the referenced media cannot be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "The capability is not enabled for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Queue transcript or transcript-and-visual ingestion.", "tags": ["YouTube"] } }, "/v1/media/youtube/{id}": { "get": { "description": "Returns the current state of one YouTube ingestion, including its job status and how much transcript and visual material has been extracted so far.", "operationId": "getYouTubeIngestion", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested YouTube ingestion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeIngestionResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Request validation failed, or a required scope/parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, malformed, unrecognized, revoked, or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The credential is valid but lacks the scope, IP allowance, or quota headroom for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No resource with that identifier exists in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Rate limit or ingestion-queue ceiling exceeded. See the RateLimit-* and Retry-After response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error. The response body carries no stack trace or internal detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "The capability is not enabled for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } }, "headers": { "RateLimit-Limit": { "description": "Request ceiling for the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the active rate-limit window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the active rate-limit window resets.", "schema": { "type": "integer" } } } } }, "security": [ { "bearer": [] } ], "summary": "Fetch a YouTube ingestion by ID.", "tags": ["YouTube"] } } }, "info": { "title": "Mnemo API", "description": "Long-term memory infrastructure for AI agents. Public endpoints require API key auth and a workspace identifier.\n\n## Errors\n\nEvery failure returns the same JSON envelope: a `statusCode`, a `message`\nthat is a string for most failures and an array of per-field strings when\nrequest validation rejected the payload, and — on most failures — an `error`\nreason phrase. A few endpoints add a stable `code` plus contextual fields\n(`memoryId`, `requiredScope`, `retryAfterSeconds`); branch on `statusCode`\nwhen `code` is absent. Responses never carry stack traces.\n\n## Rate limiting\n\nEvery response carries the IETF `RateLimit-*` header fields:\n\n- `RateLimit-Limit` — request ceiling for the active window.\n- `RateLimit-Remaining` — requests left in that window.\n- `RateLimit-Reset` — seconds until the window resets (delta-seconds).\n\nA `429` additionally carries `Retry-After`, in seconds. When more than one\nceiling applies to a route the headers describe the most constrained one, so\npacing off `RateLimit-Remaining` is always safe.", "version": "0.2.0", "contact": { "name": "Mnemo", "url": "https://mnemohq.com", "email": "founders@mnemohq.com" }, "license": { "name": "Proprietary", "url": "https://mnemohq.com/terms" } }, "tags": [], "servers": [ { "url": "https://api.mnemohq.com", "description": "Production" }, { "url": "http://localhost:4100", "description": "Local development" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "Mnemo API key", "type": "http" }, "workspace": { "type": "apiKey", "in": "header", "name": "x-workspace-id" } }, "schemas": { "ErrorResponseDto": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 400, "description": "HTTP status code, repeated in the body for convenience." }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "A containerTag or scopeType and scopeId are required for direct memory access.", "description": "Human-readable failure reason. An array of per-field messages when request validation failed, a single string otherwise." }, "error": { "type": "string", "example": "Bad Request", "description": "Reason phrase for the status code, present on NestJS' built-in exceptions." }, "code": { "type": "string", "example": "PROTECTED_MEMORY_MUTATION_DENIED", "description": "Stable machine-readable error code. Only a few endpoints emit one; branch on statusCode when it is absent." } }, "required": ["statusCode", "message"] }, "CreateMemoryScopeDto": { "type": "object", "properties": { "type": { "type": "string", "example": "user" }, "id": { "type": "string", "example": "alice" }, "tags": { "example": ["org:acme", "project:alpha"], "type": "array", "items": { "type": "string" } } }, "required": ["type", "id"] }, "MemoryItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Optional client-supplied memory identifier." }, "content": { "type": "string", "example": "Alice prefers weekly Monday updates." }, "idempotencyKey": { "type": "string", "example": "cli-2026-04-29-batch-7-item-3", "description": "Per-item idempotency key. If provided and a memory already exists with this key in the same scope, the existing memory is returned and no new write occurs." }, "memoryType": { "type": "string", "example": "preference" }, "mutationPolicy": { "type": "string", "enum": ["standard", "privileged"], "default": "standard", "description": "Mutation authorization policy. privileged requires a protected-memory management scope." }, "metadata": { "type": "object", "additionalProperties": true }, "source": { "type": "object", "additionalProperties": true } }, "required": ["content"] }, "CreateMemoriesDto": { "type": "object", "properties": { "scope": { "description": "Primary scope object. Preferred over containerTag for public API usage.", "allOf": [ { "$ref": "#/components/schemas/CreateMemoryScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope.", "deprecated": true }, "containerType": { "type": "string", "example": "user" }, "metadata": { "type": "object", "additionalProperties": true }, "source": { "type": "object", "additionalProperties": true }, "enrichmentMode": { "type": "string", "enum": ["sync", "deferred", "skip"], "default": "deferred", "description": "Controls derived LLM enrichment. Use skip for governed verbatim writes; retrieval embeddings are still created." }, "items": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/MemoryItemDto" } } }, "required": ["items"] }, "MemoryWriteStatsDto": { "type": "object", "properties": { "total": { "type": "number" }, "created": { "type": "number" }, "deduplicated": { "type": "number" } }, "required": ["total", "created", "deduplicated"] }, "MemoryWriteReceiptItemDto": { "type": "object", "properties": { "inputIndex": { "type": "number", "minimum": 0, "description": "Zero-based position of the corresponding input item." }, "memoryId": { "type": "string", "format": "uuid", "description": "Committed memory identifier." }, "status": { "type": "string", "enum": ["created", "deduplicated"], "description": "Whether this request created the memory or reused an existing equivalent." }, "searchStatus": { "type": "string", "enum": ["searchable", "stored"], "description": "'searchable' means the memory has a real embedding and is findable by vector search. 'stored' means the memory is committed and keyword-searchable (full-text search over content) but its embedding fell back to a deterministic hash because the embeddings provider was unavailable/degraded at write time — it will not surface from vector/semantic search. Re-writing the same content (same idempotencyKey or a delete + re-add) once the provider recovers produces a real embedding; there is no automatic re-embed job." } }, "required": ["inputIndex", "memoryId", "status", "searchStatus"] }, "MemoryWriteReceiptDto": { "type": "object", "properties": { "writeId": { "type": "string", "format": "uuid", "description": "Opaque identifier for this completed write operation." }, "status": { "type": "string", "enum": ["searchable", "stored"], "description": "Roll-up across every item in this write. 'searchable' (the common case) means every returned memory has a real embedding and is available to vector search. 'stored' means at least one memory is committed and keyword-searchable but not yet vector-searchable — see each item.searchStatus for which one." }, "searchableAt": { "type": "string", "format": "date-time", "description": "Time at which the complete write became searchable." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryWriteReceiptItemDto" } } }, "required": ["writeId", "status", "searchableAt", "items"] }, "CreateMemoriesResponseDto": { "type": "object", "properties": { "scopeKey": { "type": "string", "example": "user:alice" }, "scope": { "$ref": "#/components/schemas/CreateMemoryScopeDto" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Stored memory records in the same order as the submitted items." }, "stats": { "$ref": "#/components/schemas/MemoryWriteStatsDto" }, "receipt": { "$ref": "#/components/schemas/MemoryWriteReceiptDto" } }, "required": ["scopeKey", "scope", "items", "stats", "receipt"] }, "ScopeDto": { "type": "object", "properties": { "type": { "type": "string", "example": "user" }, "id": { "type": "string", "example": "alice" }, "tags": { "example": ["org:acme", "project:alpha"], "type": "array", "items": { "type": "string" } } }, "required": ["type", "id"] }, "MemoryContainerDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tag": { "type": "string", "example": "user:alice" }, "containerType": { "type": "string", "example": "user" }, "displayName": { "type": "string", "nullable": true } }, "required": ["id", "tag", "containerType", "displayName"] }, "MemoryRecordDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scopeKey": { "type": "string", "example": "user:alice" }, "scope": { "$ref": "#/components/schemas/ScopeDto" }, "container": { "$ref": "#/components/schemas/MemoryContainerDto" }, "content": { "type": "string", "example": "Alice prefers weekly Monday updates." }, "contentHash": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "memoryType": { "type": "string", "example": "preference" }, "mutationPolicy": { "type": "string", "enum": ["standard", "privileged"] }, "protectedAt": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "source": { "type": "object", "additionalProperties": true, "nullable": true }, "sourceDocumentId": { "type": "string", "format": "uuid", "nullable": true }, "eventId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "scopeKey", "scope", "container", "content", "contentHash", "idempotencyKey", "memoryType", "mutationPolicy", "protectedAt", "metadata", "source", "sourceDocumentId", "eventId", "createdAt", "updatedAt", "deletedAt" ] }, "ListMemoriesResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when this is the last page." }, "total": { "type": "integer", "description": "Total matching memories across all pages, not just this one." } }, "required": ["items", "nextCursor", "total"] }, "UpdateMemoryDto": { "type": "object", "properties": { "content": { "type": "string" }, "memoryType": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "source": { "type": "object", "additionalProperties": true, "nullable": true } } }, "UpdateMemoryProtectionDto": { "type": "object", "properties": { "mutationPolicy": { "type": "string", "enum": ["standard", "privileged"], "description": "Target mutation policy. Semantic classification remains in memoryType." } }, "required": ["mutationPolicy"] }, "DeleteMemoryPurgeCountsDto": { "type": "object", "properties": { "events": { "type": "integer" }, "embeddings": { "type": "integer" }, "factVersionSources": { "type": "integer" }, "factVersions": { "type": "integer" }, "facts": { "type": "integer" }, "factTypes": { "type": "integer" }, "conceptMentions": { "type": "integer" }, "conceptEdges": { "type": "integer" }, "conceptNodes": { "type": "integer" }, "extractedEvents": { "type": "integer" }, "snapshots": { "type": "integer" }, "deltas": { "type": "integer" }, "rollups": { "type": "integer" } }, "required": [ "events", "embeddings", "factVersionSources", "factVersions", "facts", "factTypes", "conceptMentions", "conceptEdges", "conceptNodes", "extractedEvents", "snapshots", "deltas", "rollups" ] }, "DeleteMemoryReceiptDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid", "description": "Identifier of the deletion event." }, "status": { "type": "string", "enum": ["restorable", "completed"], "description": "'restorable' when an encrypted archive was written and the memory can still be restored; 'completed' when the erasure is final." }, "completedAt": { "type": "string", "format": "date-time" }, "purged": { "description": "Row counts erased from each derived store.", "allOf": [ { "$ref": "#/components/schemas/DeleteMemoryPurgeCountsDto" } ] }, "recoveryId": { "type": "string", "format": "uuid", "description": "Present only when status is restorable." }, "restorableUntil": { "type": "string", "format": "date-time", "description": "Present only when status is restorable." } }, "required": ["id", "eventId", "status", "completedAt", "purged"] }, "DeleteMemoryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "enum": [true], "description": "Always true on a 2xx response." }, "receipt": { "description": "Erasure receipt. Emitted for privileged memories, and for every memory when complete cascading deletion is enabled for the deployment; omitted on the plain soft-delete path.", "allOf": [ { "$ref": "#/components/schemas/DeleteMemoryReceiptDto" } ] } }, "required": ["id", "deleted"] }, "RestoreMemoryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "restored": { "type": "boolean", "enum": [true], "description": "Always true on a 2xx response." }, "receiptId": { "type": "string", "format": "uuid", "description": "Identifier of the deletion receipt this restore consumed." }, "restoredAt": { "type": "string", "format": "date-time" } }, "required": ["id", "restored", "receiptId", "restoredAt"] }, "CreateDocumentDto": { "type": "object", "properties": { "scope": { "description": "Primary scope object. Preferred over containerTag for public API usage.", "allOf": [ { "$ref": "#/components/schemas/ScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope.", "deprecated": true }, "containerType": { "type": "string", "example": "user" }, "content": { "type": "string", "example": "Alice said she is evaluating two vendors and needs pricing by Friday.", "description": "Raw document content. Hard cap of 500 KB; for larger payloads split into multiple documents." }, "contentType": { "type": "string", "example": "conversation" }, "customId": { "type": "string", "example": "thread-42" }, "metadata": { "type": "object", "additionalProperties": true }, "entityContext": { "type": "object", "additionalProperties": true } }, "required": ["content", "contentType"] }, "JobAttemptsDto": { "type": "object", "properties": { "current": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["current", "max"] }, "JobErrorDto": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } }, "required": ["code", "message"] }, "DocumentJobRecordDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "queued" }, "documentId": { "type": "string", "format": "uuid" }, "retryable": { "type": "boolean", "description": "True when a failed job still has attempts left and will be retried." }, "attempts": { "$ref": "#/components/schemas/JobAttemptsDto" }, "error": { "nullable": true, "description": "Populated only while status is failed; null otherwise.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/JobErrorDto" } ] }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "documentId", "retryable", "attempts", "error", "startedAt", "finishedAt", "createdAt", "updatedAt" ] }, "DocumentRecordDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scopeKey": { "type": "string", "example": "user:alice" }, "scope": { "$ref": "#/components/schemas/ScopeDto" }, "contentType": { "type": "string", "example": "conversation" }, "contentPreview": { "type": "string", "description": "First 240 characters of the stored content." }, "content": { "type": "string", "description": "Full stored content." }, "customId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "entityContext": { "type": "object", "additionalProperties": true, "nullable": true }, "status": { "type": "string", "example": "completed" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true }, "latestJob": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DocumentJobRecordDto" } ] } }, "required": [ "id", "scopeKey", "scope", "contentType", "contentPreview", "content", "customId", "metadata", "entityContext", "status", "processedAt", "createdAt", "updatedAt", "deletedAt", "latestJob" ] }, "CreateDocumentResponseDto": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid", "description": "Poll this via GET /v1/jobs/{jobId}." }, "status": { "type": "string", "example": "queued", "description": "Current ingestion job status." }, "reused": { "type": "boolean", "description": "True when an identical prior upload was returned instead of a new one." }, "document": { "$ref": "#/components/schemas/DocumentRecordDto" }, "job": { "$ref": "#/components/schemas/DocumentJobRecordDto" } }, "required": ["documentId", "jobId", "status", "reused", "document", "job"] }, "CreateDocumentsBatchDto": { "type": "object", "properties": { "documents": { "maxItems": 50, "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CreateDocumentDto" } } }, "required": ["documents"] }, "BatchDocumentResultDto": { "type": "object", "properties": { "index": { "type": "integer", "description": "Zero-based position of the corresponding input document." }, "customId": { "type": "string", "description": "Echoed only when the input document carried a customId." }, "status": { "type": "string", "enum": ["accepted", "failed"] }, "documentId": { "type": "string", "format": "uuid", "description": "Present when accepted." }, "jobId": { "type": "string", "format": "uuid", "description": "Present when accepted." }, "ingestionStatus": { "type": "string", "example": "queued", "description": "Ingestion job status. Present when accepted." }, "reused": { "type": "boolean", "description": "Present when accepted." }, "error": { "type": "string", "description": "Present when failed. Deliberately generic so per-document internals are not disclosed." } }, "required": ["index", "status"] }, "CreateDocumentsBatchResponseDto": { "type": "object", "properties": { "success": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "description": "One entry per input document, in submission order.", "type": "array", "items": { "$ref": "#/components/schemas/BatchDocumentResultDto" } } }, "required": ["success", "failed", "results"] }, "ListDocumentsResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentRecordDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when this is the last page." } }, "required": ["items", "nextCursor"] }, "UpdateDocumentDto": { "type": "object", "properties": { "content": { "type": "string" }, "contentType": { "type": "string" }, "customId": { "type": "object" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "entityContext": { "type": "object", "additionalProperties": true, "nullable": true }, "reprocess": { "type": "boolean", "description": "Force reprocessing even if only metadata changed.", "default": false } } }, "UpdateDocumentResponseDto": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/DocumentRecordDto" }, "job": { "nullable": true, "description": "The requeued job, or null when the edit did not reprocess.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/DocumentJobRecordDto" } ] } }, "required": ["document", "job"] }, "DeleteDocumentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "enum": [true], "description": "Always true on a 2xx response." }, "forgottenMemories": { "type": "integer", "description": "Derived memories soft-deleted alongside the document." }, "failedJobs": { "type": "integer", "description": "Queued or in-flight ingestion jobs force-failed." } }, "required": ["id", "deleted", "forgottenMemories", "failedJobs"] }, "JobRecordDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "queued", "description": "Lifecycle state. queued and processing are non-terminal; completed and failed are terminal." }, "documentId": { "type": "string", "format": "uuid", "description": "Document this job ingests." }, "scopeKey": { "type": "string", "example": "user:alice" }, "scope": { "$ref": "#/components/schemas/ScopeDto" }, "retryable": { "type": "boolean", "description": "True when a failed job still has attempts left and will be retried." }, "attempts": { "$ref": "#/components/schemas/JobAttemptsDto" }, "error": { "nullable": true, "description": "Populated only while status is failed; null otherwise.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/JobErrorDto" } ] }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "documentId", "scopeKey", "scope", "retryable", "attempts", "error", "startedAt", "finishedAt", "createdAt", "updatedAt" ] }, "ListJobsResponseDto": { "type": "object", "properties": { "items": { "description": "Jobs in the order their ids were requested. Ids that do not resolve are omitted rather than returned as null, so this array can be shorter than the request.", "type": "array", "items": { "$ref": "#/components/schemas/JobRecordDto" } } }, "required": ["items"] }, "SearchRequestDto": { "type": "object", "properties": { "scope": { "description": "Primary scope object. Preferred over containerTag for public API usage.", "allOf": [ { "$ref": "#/components/schemas/ScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope.", "deprecated": true }, "q": { "type": "string", "example": "What does Alice need this week?" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeDto" } }, "containerTags": { "example": ["user:alice", "project:alpha"], "deprecated": true, "type": "array", "items": { "type": "string" } }, "searchMode": { "type": "string", "enum": ["hybrid", "memories", "documents"], "default": "hybrid" }, "limit": { "type": "number", "minimum": 1, "maximum": 50, "default": 10 }, "filters": { "type": "object", "additionalProperties": true }, "includeSources": { "type": "boolean", "default": false }, "intentOverride": { "type": "string", "description": "Override the automatic query intent classification. When set, the query router is skipped.", "enum": [ "temporal", "factual", "multi_hop", "simple_recall", "knowledge_update", "aggregation" ] }, "agentic": { "type": "boolean", "description": "Enable agentic retrieval loop. When true, low-confidence results trigger automatic query reformulation, iterative deepening, and self-verification. Adds latency but improves recall. Implicitly upgrades `mode` to `precise` for backward compatibility.", "default": false }, "mode": { "type": "string", "description": "Retrieval mode. `fast` (default): hot-path lookup — embed + intent router + parallel SQL + RRF + embedding-based concept-graph boost (uses pre-computed concept embeddings extracted at ingest time, no LLM call on the query side). Target avg ~2.5s, p95 ~5s. `precise`: full pipeline with LLM intent router, semantic bridge expansion, LLM concept extraction, reranker, and optional agentic loop. Highest recall at the cost of 20–50s. If `mode` is unset and `agentic` is true, mode is implicitly `precise` for backward compatibility.", "enum": ["fast", "precise"], "default": "fast" }, "strategies": { "type": "array", "description": "Additive opt-in retrieval strategies, applied on top of the always-on baseline (vector + keyword + fact + RRF). Force-enables specific strategies for this query — never disables the baseline. Omit to let the intent router decide. The response echoes which strategies actually fired in `strategiesRan`.", "example": ["temporal", "graph"], "items": { "type": "string", "enum": ["temporal", "graph", "rerank", "agentic"] } }, "excludeIds": { "description": "Memory/document/fact IDs to exclude from results — dedup-aware retrieval. Pass the IDs already in your agent's context (e.g. from a prior /v1/profile or /v1/search call) and they are filtered out, so you never re-retrieve what the agent already holds. Excluded BEFORE ranking, so `limit` is still honored from the remaining results.", "example": ["mem_a1b2", "mem_c3d4"], "type": "array", "items": { "type": "string" } } }, "required": ["q"] }, "SearchResultDto": { "type": "object", "properties": { "resultType": { "type": "string", "enum": ["memory", "document", "fact"] }, "score": { "type": "number", "description": "Fused relevance score; higher is better." }, "scopeKey": { "type": "string", "example": "user:alice" }, "content": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "memoryId": { "type": "string", "format": "uuid", "description": "Set when resultType is memory." }, "documentId": { "type": "string", "format": "uuid", "description": "Set when resultType is document, and on a memory that was derived from a document." }, "factId": { "type": "string", "format": "uuid", "description": "Set when resultType is fact." }, "memoryType": { "type": "string", "example": "preference", "description": "Memories only." }, "contentType": { "type": "string", "example": "conversation", "description": "Documents only." }, "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"], "description": "Memories and facts only. Negative polarity marks a hard constraint." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Memories and documents only." }, "sources": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Provenance and per-strategy scores. Returned only when the request set includeSources=true. The key set varies by resultType: memories carry provenance/vectorSimilarity/lexicalScore, documents add customId/contentType, facts carry kind plus scores." } }, "required": ["resultType", "score", "scopeKey", "content", "metadata", "createdAt"] }, "SearchLatencyDto": { "type": "object", "properties": { "parallelMs": { "type": "integer", "description": "Wall time spent running strategies in parallel." }, "strategyMs": { "type": "integer", "description": "Summed time across individual strategies." }, "fusionMs": { "type": "integer", "description": "Time spent fusing strategy results." }, "rerankerMs": { "type": "integer", "description": "Time spent reranking; 0 when the reranker did not run." }, "totalMs": { "type": "integer", "description": "End-to-end retrieval time." } }, "required": ["parallelMs", "strategyMs", "fusionMs", "rerankerMs", "totalMs"] }, "SearchResponseDto": { "type": "object", "properties": { "results": { "description": "Ranked hits, or an empty array when the query was abstained on.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultDto" } }, "positivePreferences": { "description": "The subset of results whose polarity is not negative.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultDto" } }, "hardConstraints": { "description": "The subset of results whose polarity is negative — things the agent must not do.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultDto" } }, "searchMode": { "type": "string", "enum": ["hybrid", "memories", "documents"], "description": "Echo of the effective search mode." }, "queryIntent": { "type": "string", "enum": [ "temporal", "factual", "multi_hop", "simple_recall", "knowledge_update", "aggregation" ], "description": "Intent the router classified the query as, or the supplied intentOverride." }, "queryIntentConfidence": { "type": "number", "description": "Router confidence in queryIntent, 0-1." }, "strategiesRan": { "example": ["vector", "lexical", "fact"], "description": "Retrieval strategies that actually ran for this query.", "type": "array", "items": { "type": "string" } }, "abstained": { "type": "boolean", "description": "True when confidence was too low to return results. results, positivePreferences and hardConstraints are then all empty." }, "latency": { "$ref": "#/components/schemas/SearchLatencyDto" }, "reranked": { "type": "boolean", "description": "True when the reranker stage ran." }, "rawBestVectorSim": { "type": "number", "description": "Best raw vector similarity seen before fusion; useful for calibrating your own thresholds." }, "abstentionReason": { "type": "string", "description": "Present only when abstained is true." }, "conceptExpansion": { "type": "object", "additionalProperties": true, "description": "Concept-graph expansion trace (seedConcepts, expandedConcepts, edgesTraversed). Present only when the graph strategy expanded the query." }, "semanticBridge": { "type": "object", "additionalProperties": true, "description": "Synonym-bridge trace (originalTerms, bridgedTerms, bridges). Present only when the semantic bridge fired." }, "entityGraph": { "type": "object", "additionalProperties": true, "description": "Entity-graph trace (resolvedEntities, graphNodesVisited, summaryHits, connectedMemories). Present only when the entity graph was traversed." }, "verification": { "type": "object", "additionalProperties": true, "description": "Answer-verification verdict (answered, confidence, and reason on the full loop). Present only on agentic precise retrieval." }, "agenticSteps": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Per-round agentic trace (round, action, query, durationMs). Present only when the agentic loop ran." } }, "required": [ "results", "positivePreferences", "hardConstraints", "searchMode", "queryIntent", "queryIntentConfidence", "strategiesRan", "abstained", "latency", "reranked", "rawBestVectorSim" ] }, "ProfileRequestDto": { "type": "object", "properties": { "scope": { "description": "Primary scope object. Preferred over containerTag for public API usage.", "allOf": [ { "$ref": "#/components/schemas/ScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope.", "deprecated": true }, "q": { "type": "string", "example": "What should I know before replying to Alice?", "description": "Optional question. When provided AND `includeSearch=true`, the profile is augmented with `?q=` results from the hybrid search pipeline. Triggering search adds 1-15 LLM calls and seconds of latency, so it is opt-in." }, "threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0 }, "includeSearch": { "type": "boolean", "description": "Run hybrid search and include results in the response. Default false because search is expensive (LLM-driven). Even when true, you must still pass `q`.", "default": false }, "staticLimit": { "type": "number", "description": "Max number of static facts to return.", "minimum": 1, "maximum": 50, "default": 12 }, "dynamicLimit": { "type": "number", "description": "Max number of dynamic items (memories + documents).", "minimum": 1, "maximum": 50, "default": 10 }, "itemMaxBytes": { "type": "number", "description": "Max bytes per dynamic item content (sliced if larger).", "minimum": 100, "maximum": 8000, "default": 600 } } }, "ProfileStaticFactDto": { "type": "object", "properties": { "key": { "type": "string", "example": "timezone" }, "value": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "additionalProperties": true } ], "description": "Extracted value. Scalar, object, or null depending on the fact type." }, "confidence": { "type": "number", "nullable": true }, "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"] } }, "required": ["key", "value", "confidence", "polarity"] }, "ProfileDynamicItemDto": { "type": "object", "properties": { "resultType": { "type": "string", "enum": ["memory", "document"] }, "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "memoryType": { "type": "string", "example": "preference", "description": "Memories only." }, "polarity": { "type": "string", "enum": ["positive", "negative", "neutral"], "description": "Memories only." }, "contentType": { "type": "string", "example": "conversation", "description": "Documents only." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["resultType", "id", "content", "metadata", "createdAt", "updatedAt"] }, "ProfileHardConstraintMemoryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["id", "content", "createdAt", "updatedAt"] }, "ProfileHardConstraintsDto": { "type": "object", "properties": { "facts": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileStaticFactDto" } }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileHardConstraintMemoryDto" } } }, "required": ["facts", "memories"] }, "ProfileBodyDto": { "type": "object", "properties": { "static": { "description": "Stable extracted facts about the scope.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileStaticFactDto" } }, "dynamic": { "description": "Recent memories and documents for the scope.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileDynamicItemDto" } }, "positivePreferences": { "description": "Static facts whose polarity is not negative.", "type": "array", "items": { "$ref": "#/components/schemas/ProfileStaticFactDto" } }, "hardConstraints": { "description": "Negative-polarity facts and memories the agent must respect.", "allOf": [ { "$ref": "#/components/schemas/ProfileHardConstraintsDto" } ] } }, "required": ["static", "dynamic", "positivePreferences", "hardConstraints"] }, "ProfilePromptGuidanceDto": { "type": "object", "properties": { "hardConstraintsNotice": { "type": "string", "description": "Ready-to-paste sentence telling the model how to treat hardConstraints." } }, "required": ["hardConstraintsNotice"] }, "ProfileStatsDto": { "type": "object", "properties": { "staticTotal": { "type": "integer" }, "dynamicTotal": { "type": "integer" }, "truncatedItems": { "type": "integer", "description": "Dynamic items whose content was sliced to itemMaxBytes." }, "cached": { "type": "boolean", "description": "True when this profile was served from cache." } }, "required": ["staticTotal", "dynamicTotal", "truncatedItems", "cached"] }, "ProfileResponseDto": { "type": "object", "properties": { "scopeKey": { "type": "string", "example": "user:alice" }, "scope": { "$ref": "#/components/schemas/ScopeDto" }, "profile": { "$ref": "#/components/schemas/ProfileBodyDto" }, "promptGuidance": { "$ref": "#/components/schemas/ProfilePromptGuidanceDto" }, "stats": { "$ref": "#/components/schemas/ProfileStatsDto" }, "searchResults": { "description": "Hybrid-search hits. Present only when the request set includeSearch=true and supplied q.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultDto" } }, "searchPositivePreferences": { "description": "Non-negative subset of searchResults. Same presence condition.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultDto" } }, "searchHardConstraints": { "description": "Negative subset of searchResults. Same presence condition.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultDto" } } }, "required": ["scopeKey", "scope", "profile", "promptGuidance", "stats"] }, "SubscribeNewsletterDto": { "type": "object", "properties": {} }, "NewsletterSubscriptionResponseDto": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [true], "description": "Always true. The confirmation email is sent out of band; this does not mean the address is subscribed yet." } }, "required": ["accepted"] }, "EstimateYouTubeDto": { "type": "object", "properties": { "url": { "type": "string", "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "mode": { "type": "string", "enum": ["transcript", "transcript_and_visuals"], "default": "transcript" } }, "required": ["url", "mode"] }, "YouTubeQuotaDto": { "type": "object", "properties": { "used": { "type": "integer", "description": "Metered seconds already consumed this period." }, "limit": { "type": "integer", "description": "Metered seconds allowed this period." }, "remaining": { "type": "integer", "description": "Metered seconds still available." }, "requested": { "type": "integer", "description": "Seconds this video would consume." }, "willFit": { "type": "boolean", "description": "True when requested fits inside remaining." } }, "required": ["used", "limit", "remaining", "requested", "willFit"] }, "YouTubeEstimateResponseDto": { "type": "object", "properties": { "videoId": { "type": "string", "example": "dQw4w9WgXcQ" }, "canonicalUrl": { "type": "string", "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "title": { "type": "string" }, "durationSeconds": { "type": "integer" }, "durationMinutes": { "type": "integer", "description": "durationSeconds rounded up to whole minutes." }, "mode": { "type": "string", "enum": ["transcript", "transcript_and_visuals"] }, "meter": { "type": "string", "enum": ["youtube_transcript_seconds", "youtube_visual_seconds"], "description": "Usage meter this ingestion would bill against." }, "quota": { "$ref": "#/components/schemas/YouTubeQuotaDto" } }, "required": [ "videoId", "canonicalUrl", "title", "durationSeconds", "durationMinutes", "mode", "meter", "quota" ] }, "CreateYouTubeIngestionDto": { "type": "object", "properties": { "scope": { "description": "Primary scope object. Preferred over containerTag for public API usage.", "allOf": [ { "$ref": "#/components/schemas/ScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope.", "deprecated": true }, "url": { "type": "string", "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "mode": { "type": "string", "enum": ["transcript", "transcript_and_visuals"], "default": "transcript" }, "customId": { "type": "string", "example": "onboarding-demo" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": ["url", "mode"] }, "YouTubeIngestionErrorDto": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } }, "required": ["code", "message"] }, "YouTubeIngestionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "videoId": { "type": "string", "example": "dQw4w9WgXcQ" }, "sourceUrl": { "type": "string", "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "title": { "type": "string" }, "durationSeconds": { "type": "integer" }, "mode": { "type": "string", "enum": ["transcript", "transcript_and_visuals"] }, "status": { "type": "string", "example": "queued", "description": "Status of the backing ingestion job, not of the video row." }, "sourceDocumentId": { "type": "string", "format": "uuid", "description": "Document the transcript is stored as." }, "jobId": { "type": "string", "format": "uuid", "description": "Poll this via GET /v1/jobs/{jobId}." }, "scopeKey": { "type": "string", "example": "user:alice" }, "scope": { "$ref": "#/components/schemas/ScopeDto" }, "transcriptSegmentCount": { "type": "integer" }, "visualObservationCount": { "type": "integer" }, "error": { "nullable": true, "description": "Populated only while status is failed; null otherwise.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/YouTubeIngestionErrorDto" } ] }, "reused": { "type": "boolean", "description": "True when an existing non-failed ingestion was returned instead of queueing a new one. Always false on fetch." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "videoId", "sourceUrl", "title", "durationSeconds", "mode", "status", "sourceDocumentId", "jobId", "scopeKey", "scope", "transcriptSegmentCount", "visualObservationCount", "error", "reused", "createdAt", "updatedAt" ] } } } }