{ "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": [] }, { "oauth2": ["memories:write"] } ], "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" } }, { "name": "since", "required": false, "in": "query", "description": "Only memories created at or after this instant.", "schema": { "format": "date-time", "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "until", "required": false, "in": "query", "description": "Only memories created at or before this instant.", "schema": { "format": "date-time", "example": "2026-09-02T00:00:00Z", "type": "string" } }, { "name": "createdByKind", "required": false, "in": "query", "description": "Only memories written by this kind of principal.", "schema": { "example": "api_key", "type": "string", "enum": ["api_key", "mcp", "user", "connector", "inbound", "system"] } }, { "name": "memoryType", "required": false, "in": "query", "description": "Only memories of this type. \"note\" also matches untyped \"memory\" rows.", "schema": { "example": "reminder", "type": "string", "enum": [ "memory", "preference", "fact", "observation", "event", "note", "reminder", "goal" ] } } ], "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": [] }, { "oauth2": ["memories:read"] } ], "summary": "List stored memories within a required scope or legacy containerTag.", "tags": ["Memories"] } }, "/v1/memories/merge": { "post": { "description": "Folds 2 to 20 memories of the same container into one. Keep one of them with `into` (it retains its id and gains `metadata.mergedFromIds`) or write a new merged memory from `content`. Every other id is soft-deleted (restorable via restoreMemory) with `metadata.mergedIntoId`. Idempotent on `mergeKey` (default: a hash of the sorted ids): replaying a completed merge returns its survivor with `replayed: true`. Requires memories:write and memories:delete and the Memory Inbox feature (503 FEATURE_DISABLED when off). Stable error codes: MERGE_SOURCE_INVALID (400), MERGE_CROSS_CONTAINER (400), CONTAINER_TAG_REQUIRED (400), MERGE_PROTECTED (403), MERGE_KEY_REUSED (409).", "operationId": "mergeMemories", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeMemoriesDto" } } } }, "responses": { "200": { "description": "Replay of a completed merge (same mergeKey): the existing survivor with `replayed: true`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeMemoriesResponseDto" } } }, "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" } } } }, "201": { "description": "The surviving memory plus the source ids that were folded in and soft-deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeMemoriesResponseDto" } } }, "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" } } } }, "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": "Merge memories of one container into a single survivor.", "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": [] }, { "oauth2": ["memories:read"] } ], "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": [] }, { "oauth2": ["memories:write"] } ], "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": "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": "permanent", "required": false, "in": "query", "description": "When true, permanently deletes the memory instead of the recoverable soft delete. Accepts only \"true\" or \"false\"; omitted means false.", "schema": { "example": true, "type": "boolean" } } ], "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": [] }, { "oauth2": ["memories:delete"] } ], "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": [] }, { "oauth2": ["search:read"] } ], "summary": "Search across memories and documents with hybrid retrieval.", "tags": ["Search"] } }, "/v1/answer": { "post": { "description": "Answers a natural-language question from the named scopes. By default it also returns up to 10 retrieved snippets as citations; the list can be empty or missing, and includeCitations: false turns it off. When nothing in scope matches, the answer usually tells you so, but the server can retry and return a best-effort answer instead, so check it against the citations. Needs the answer:read scope, which only API keys carry (OAuth access tokens get a 403). Responds 201 because the query travels in the request body.", "operationId": "answerQuestion", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerRequestDto" } } } }, "responses": { "201": { "description": "The answer, any cited snippets, and timing stats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerResponseDto" } } }, "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: q is missing, a field is malformed, or a property is unknown.", "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": "A named scope doesn't exist 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 exceeded. See the RateLimit-* 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": "Answer a natural-language question from one or more memory scopes.", "tags": ["Answer"] } }, "/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"] } }, "/v1/people": { "post": { "description": "Creates one memory container per person (tag person:) holding their contact details, important dates and aliases. The slug is derived from displayName unless given, and is immutable afterwards.", "operationId": "createPerson", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePersonDto" } } } }, "responses": { "201": { "description": "The new person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDto" } } }, "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" } } } }, "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": "Create a person.", "tags": ["People"] }, "get": { "description": "Cursor-paginated list of people, newest first, with memory and open-reminder counts. Archived people are hidden unless includeArchived=true.", "operationId": "listPeople", "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": "q", "required": false, "in": "query", "description": "Case-insensitive match on display name, or substring of the email.", "schema": { "maxLength": 120, "example": "alice", "type": "string" } }, { "name": "includeArchived", "required": false, "in": "query", "description": "Include archived people. Accepts only \"true\" or \"false\"; omitted means false.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of people.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPeopleResponseDto" } } }, "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" } } } }, "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": "List people.", "tags": ["People"] } }, "/v1/people/{slug}": { "get": { "description": "Returns the person with counts. Archived people return 404 PERSON_NOT_FOUND.", "operationId": "getPerson", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Person slug (lowercase alphanumerics and single hyphens).", "schema": { "example": "alice-smith", "type": "string" } } ], "responses": { "200": { "description": "The person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDto" } } }, "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 person by slug.", "tags": ["People"] }, "patch": { "description": "Partial update: omitted fields are untouched, explicit null clears a field, arrays replace wholesale. archived toggles the archive state.", "operationId": "updatePerson", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Person slug (lowercase alphanumerics and single hyphens).", "schema": { "example": "alice-smith", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonDto" } } } }, "responses": { "200": { "description": "The updated person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDto" } } }, "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" } } } }, "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": "Update a person.", "tags": ["People"] }, "delete": { "description": "Archives the person (their container is kept; the event stream is immutable). With deleteMemories=true every memory in the container is soft-deleted first, up to 500.", "operationId": "archivePerson", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Person slug (lowercase alphanumerics and single hyphens).", "schema": { "example": "alice-smith", "type": "string" } }, { "name": "deleteMemories", "required": false, "in": "query", "description": "Also soft-delete every memory in the person container (max 500, else 409 TOO_MANY_MEMORIES). Accepts only \"true\" or \"false\"; omitted means false.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The person is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchivePersonResponseDto" } } }, "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" } } } }, "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": "Archive a person.", "tags": ["People"] } }, "/v1/people/{slug}/summary": { "get": { "description": "Runs the fast reader over the person container (a general summary, or your question q) and returns the answer with citations, plus open reminders and the most recent memories. Abstains within a fixed time budget rather than failing.", "operationId": "getPersonSummary", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Person slug (lowercase alphanumerics and single hyphens).", "schema": { "example": "alice-smith", "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Question to answer over this person's memories. Defaults to a general summary.", "schema": { "maxLength": 2000, "type": "string" } } ], "responses": { "200": { "description": "The summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonSummaryDto" } } }, "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": "Summarise what is known about a person.", "tags": ["People"] } }, "/v1/reminders": { "post": { "description": "Writes a memory of type \"reminder\" with a due time into a person container (personSlug) or any container (containerTag / scope). Exactly one target is required.", "operationId": "createReminder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReminderDto" } } } }, "responses": { "201": { "description": "The new reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderDto" } } }, "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" } } } }, "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": "Create a reminder.", "tags": ["Reminders"] }, "get": { "description": "Open reminders (default) soonest first, completed ones most recently updated first, or all. Filter by due window, container type or container tag.", "operationId": "listReminders", "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": "status", "required": false, "in": "query", "schema": { "default": "open", "type": "string", "enum": ["open", "completed", "all"] } }, { "name": "dueAfter", "required": false, "in": "query", "description": "Only reminders due at or after this instant.", "schema": { "format": "date-time", "type": "string" } }, { "name": "dueBefore", "required": false, "in": "query", "description": "Only reminders due at or before this instant.", "schema": { "format": "date-time", "type": "string" } }, { "name": "days", "required": false, "in": "query", "description": "Shorthand for dueBefore = now + days.", "schema": { "minimum": 1, "maximum": 365, "type": "number" } }, { "name": "containerType", "required": false, "in": "query", "description": "Only reminders whose container has this type.", "schema": { "example": "person", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "schema": { "example": "person:alice-smith", "type": "string" } } ], "responses": { "200": { "description": "A page of reminders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRemindersResponseDto" } } }, "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" } } } }, "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": "List reminders.", "tags": ["Reminders"] } }, "/v1/reminders/upcoming": { "get": { "description": "Buckets open reminders by the caller's local day (timezone, default UTC) over the next N days, and lists people's important dates falling in the window.", "operationId": "listUpcomingReminders", "parameters": [ { "name": "days", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 90, "default": 7, "type": "number" } }, { "name": "timezone", "required": false, "in": "query", "description": "IANA zone used to bucket reminders into overdue / today / upcoming.", "schema": { "default": "UTC", "example": "America/New_York", "type": "string" } }, { "name": "containerType", "required": false, "in": "query", "schema": { "example": "person", "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "schema": { "example": "person:alice-smith", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } } ], "responses": { "200": { "description": "Bucketed reminders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpcomingRemindersResponseDto" } } }, "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" } } } }, "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": "Overdue, due-today and upcoming reminders plus important dates.", "tags": ["Reminders"] } }, "/v1/reminders/{memoryId}": { "patch": { "description": "Updates the content, due time and/or metadata of a reminder. The memory is looked up by id across the workspace; a non-reminder memory is rejected with 400 NOT_A_REMINDER.", "operationId": "updateReminder", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReminderDto" } } } }, "responses": { "200": { "description": "The updated reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderDto" } } }, "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": "Edit or reschedule a reminder.", "tags": ["Reminders"] } }, "/v1/reminders/{memoryId}/complete": { "post": { "description": "Clears the due time and records completedAt / originalDueAt in the reminder metadata. Already-completed reminders return 409.", "operationId": "completeReminder", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The completed reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderDto" } } }, "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" } } } }, "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": "Complete a reminder.", "tags": ["Reminders"] } }, "/v1/reminders/{memoryId}/reopen": { "post": { "description": "Sets a new due time and clears completedAt.", "operationId": "reopenReminder", "parameters": [ { "name": "memoryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReopenReminderDto" } } } }, "responses": { "200": { "description": "The reopened reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderDto" } } }, "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": "Reopen a completed reminder.", "tags": ["Reminders"] } }, "/v1/timeline": { "get": { "description": "Merges the container's memories (at write time), open reminders (at due time), source documents (at ingest time) and, when requested, engine events into one cursor-paginated stream ordered by occurredAt. Defaults to memory, reminder and document; pass types=...,event to include events. A container that does not exist yet yields an empty page with container null. Requires the timeline:read scope and the deployment flag MEMORY_API_TIMELINE_ENABLED.", "operationId": "getContainerTimeline", "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": "from", "required": false, "in": "query", "description": "Only items that occurred at or after this instant.", "schema": { "format": "date-time", "example": "2026-08-01T00:00:00Z", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Only items that occurred at or before this instant.", "schema": { "format": "date-time", "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "types", "required": false, "in": "query", "description": "Comma-separated item types to include: memory | reminder | document | event. Defaults to memory,reminder,document — engine events are opt-in.", "schema": { "example": "memory,reminder,document", "type": "string" } }, { "name": "direction", "required": false, "in": "query", "description": "desc = newest first (default), asc = oldest first.", "schema": { "default": "desc", "type": "string", "enum": ["desc", "asc"] } }, { "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": "Container to read, as \":\". Required for API keys unless scopeType + scopeId are given; ignored for MCP tokens, which read the container of their grant (X-Galdo-Container).", "schema": { "example": "user:alice", "type": "string" } } ], "responses": { "200": { "description": "A page of the container timeline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineResponseDto" } } }, "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" } } } }, "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": "Read one container as a single time-ordered stream.", "tags": ["Timeline"] } }, "/v1/inbound/channels": { "post": { "description": "Registers a phone number against a container and returns a six-digit verification code — shown only in this response. The channel stays pending until a message containing that code arrives from the phone; from then on every text becomes a note memory and every voice note is transcribed into one. A number can be linked to a single workspace at a time.", "operationId": "createInboundChannel", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboundChannelDto" } } } }, "responses": { "201": { "description": "Channel created in the pending state, with its one-time verification code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundChannelDto" } } }, "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" } } } }, "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": "Link a phone number so its WhatsApp or SMS messages become memories.", "tags": ["Inbound capture"] }, "get": { "description": "Returns channels newest-first with cursor pagination. Phone numbers are masked and verification codes are never included.", "operationId": "listInboundChannels", "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" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboundChannelsResponseDto" } } }, "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" } } } }, "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": "List the linked phone numbers in this workspace.", "tags": ["Inbound capture"] } }, "/v1/inbound/channels/{id}": { "get": { "description": "Returns the channel, its status and last-message time. The phone number is masked.", "operationId": "getInboundChannel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundChannelDto" } } }, "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 one linked phone number.", "tags": ["Inbound capture"] }, "patch": { "description": "Changes the container that receives captures, or toggles the channel between active and disabled. A pending channel cannot be activated here — it activates when the phone sends its verification code.", "operationId": "updateInboundChannel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboundChannelDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundChannelDto" } } }, "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": "Re-target or disable a linked phone number.", "tags": ["Inbound capture"] }, "delete": { "description": "Removes the channel and frees the number for re-registration. Memories already captured are untouched.", "operationId": "deleteInboundChannel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteInboundChannelResponseDto" } } }, "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": "Unlink a phone number.", "tags": ["Inbound capture"] } }, "/v1/inbound/channels/{id}/regenerate-code": { "post": { "description": "Invalidates the previous code. The phone must send the new code before further messages are captured. The code is returned only in this response.", "operationId": "regenerateInboundChannelCode", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundChannelDto" } } }, "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": "Issue a new verification code and reset the channel to pending.", "tags": ["Inbound capture"] } }, "/v1/meetings/upcoming": { "get": { "description": "Upcoming Google Calendar events across every connected calendar in the workspace, soonest first, with attendees resolved to workspace people by email. Returns an empty page with connections: [] when no calendar is connected. Requires MEMORY_API_MEETINGS_ENABLED and the connector framework.", "operationId": "listUpcomingMeetings", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Horizon in days from now.", "schema": { "minimum": 1, "maximum": 30, "default": 7, "example": 7, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous page.", "schema": { "type": "string" } }, { "name": "containerTag", "required": false, "in": "query", "description": "Restrict to one Google Calendar connection's container.", "schema": { "maxLength": 512, "example": "calendar:me@example.com", "type": "string" } } ], "responses": { "200": { "description": "A page of upcoming meetings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUpcomingMeetingsResponseDto" } } }, "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" } } } }, "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": "List upcoming meetings.", "tags": ["Meetings"] } }, "/v1/meetings/{documentId}": { "get": { "description": "Returns a calendar event document (past or upcoming) with attendees resolved to people. Documents of another workspace or non-calendar documents return 404 MEETING_NOT_FOUND.", "operationId": "getMeeting", "parameters": [ { "name": "documentId", "required": true, "in": "path", "description": "SourceDocument id of the calendar event (from the upcoming list).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The meeting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingDto" } } }, "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 one meeting.", "tags": ["Meetings"] } }, "/v1/meetings/{documentId}/brief": { "get": { "description": "Composes a briefing for the meeting: a fast-reader answer (your question q, or a default \"what do I know, what did we last discuss, what is open\" question) over the calendar container and the matched people, cached for 15 minutes; each matched person with their open reminders and recent memories; and up to five previous meetings sharing an attendee. The reader section is null when it does not respond within the time budget; the other sections still render.", "operationId": "getMeetingBrief", "parameters": [ { "name": "documentId", "required": true, "in": "path", "description": "SourceDocument id of the calendar event (from the upcoming list).", "schema": { "format": "uuid", "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Question to answer over the meeting container and the matched people. Defaults to a pre-meeting briefing question.", "schema": { "maxLength": 2000, "type": "string" } } ], "responses": { "200": { "description": "The brief.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingBriefDto" } } }, "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": "Pre-meeting brief.", "tags": ["Meetings"] } }, "/v1/brief": { "get": { "description": "Composes the day in the given timezone: overdue / due-today / coming-up reminders and people's important dates (core), what was captured in the 24 hours before the day (core), a fast-reader answer to \"what did I promise or say I would follow up on\" (followUps; cached 30 minutes, metered as one answer call on a miss, null when the reader does not respond within the time budget) and the day's meetings (meetings; null unless MEMORY_API_MEETINGS_ENABLED and a calendar is connected). Sections not requested are null. The brief is computed, never stored. Requires MEMORY_API_BRIEF_ENABLED.", "operationId": "getDailyBrief", "parameters": [ { "name": "containerTag", "required": false, "in": "query", "description": "Container to brief on, as \":\". Required for API keys unless scopeType + scopeId are given; the dashboard may omit it to brief the whole workspace.", "schema": { "maxLength": 512, "example": "user:alice", "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Local calendar day to brief, YYYY-MM-DD. Defaults to today in `timezone`.", "schema": { "example": "2026-09-02", "type": "string" } }, { "name": "timezone", "required": false, "in": "query", "description": "IANA time zone that defines \"today\". Unknown zones return 400 INVALID_TIMEZONE.", "schema": { "maxLength": 64, "default": "UTC", "example": "America/New_York", "type": "string" } }, { "name": "days", "required": false, "in": "query", "description": "How many days ahead the \"coming up\" reminders and important dates reach.", "schema": { "minimum": 1, "maximum": 30, "default": 7, "example": 7, "type": "number" } }, { "name": "sections", "required": false, "in": "query", "description": "Comma-separated sections to compute: core | followUps | meetings. Defaults to all. Sections not requested are null in the response.", "schema": { "example": "core,meetings", "type": "string" } }, { "name": "scopeType", "required": false, "in": "query", "description": "Scope type; pair with scopeId as an alternative to containerTag.", "schema": { "example": "user", "type": "string" } }, { "name": "scopeId", "required": false, "in": "query", "schema": { "example": "alice", "type": "string" } } ], "responses": { "200": { "description": "The brief.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyBriefDto" } } }, "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" } } } }, "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": "Daily brief for one container.", "tags": ["Brief"] } } }, "info": { "title": "Galdo API", "description": "The API to Galdo's company memory: write to it, search it, and ask it, with sources. 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.\n\n## OAuth 2.0\n\nBesides workspace API keys, operations marked with the `oauth2` scheme accept\nan OAuth 2.0 bearer token from Galdo's authorization server, issuer\n`https://api.mnemohq.com/v1/mcp/oauth`. It is the same authorization server the hosted MCP server\nuses, so one authorization covers both surfaces. Discovery metadata lives at\n`/.well-known/oauth-authorization-server`; the flow is authorization code with\nPKCE (`S256` only) and clients may self-register via RFC 7591 dynamic client\nregistration at `https://api.mnemohq.com/v1/mcp/oauth/register`.\n\nTokens carry a workspace, a scope set, and optionally a set of memory\ncontainers. Available scopes: `memories:read`, `memories:write`, `memories:delete`, `search:read`.\nOperations not marked with the `oauth2` scheme (documents, jobs, profile, answer,\nexports, and the personal-memory endpoints) are API-key only and reject OAuth\ntokens with a `403`.\nA token scoped to specific containers is confined to them on every operation;\nname the one to act on with the `X-Galdo-Container` request header.\n\nFailures follow RFC 6750: a `401` carries\n`WWW-Authenticate: Bearer error=\"invalid_token\"`, and a `403` for a missing\nscope carries `error=\"insufficient_scope\"` with the required `scope`.", "version": "0.3.0", "contact": { "name": "Galdo", "url": "https://getgaldo.com", "email": "shah@mnemohq.com" }, "license": { "name": "Proprietary", "url": "https://getgaldo.com/terms" } }, "tags": [], "servers": [ { "url": "https://api.mnemohq.com", "description": "Production" }, { "url": "http://localhost:4100", "description": "Local development" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "Galdo API key", "type": "http" }, "workspace": { "type": "apiKey", "in": "header", "name": "x-workspace-id" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.mnemohq.com/v1/mcp/oauth/authorize", "tokenUrl": "https://api.mnemohq.com/v1/mcp/oauth/token", "refreshUrl": "https://api.mnemohq.com/v1/mcp/oauth/token", "scopes": { "memories:read": "Read memories in the authorized workspace.", "memories:write": "Create and update memories in the authorized workspace.", "memories:delete": "Delete memories in the authorized workspace.", "search:read": "Run retrieval queries against the authorized workspace." } } }, "description": "OAuth 2.0 authorization code flow with PKCE against Galdo’s authorization server (issuer https://api.mnemohq.com/v1/mcp/oauth). The resulting access token is accepted on the operations that map onto a granted scope; the remaining operations are API-key only." } }, "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" }, "dueAt": { "type": "string", "format": "date-time", "example": "2026-09-15T09:00:00Z", "description": "Reminder due time. Setting it makes the memory a reminder: memoryType defaults to \"reminder\" when omitted and any other explicit memoryType is rejected with 400 NOT_A_REMINDER." }, "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"] }, "MergeMemoriesDto": { "type": "object", "properties": { "scope": { "description": "Scope holding every memory in `ids`. Required (or containerTag) for API keys.", "allOf": [ { "$ref": "#/components/schemas/CreateMemoryScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope.", "deprecated": true }, "ids": { "minItems": 2, "maxItems": 20, "description": "Memory ids to merge (2..20, unique, all in the same container). Every id not kept as `into` is soft-deleted.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "into": { "type": "string", "format": "uuid", "description": "Survivor id. Must be one of `ids`; it keeps its id and gains the merge metadata. Omit to create a new merged memory from `content`." }, "content": { "type": "string", "example": "Alice prefers weekly Monday updates, sent before 9am.", "description": "Merged text. Required when `into` is omitted; an optional override of the survivor content when `into` is given." }, "memoryType": { "type": "string", "example": "preference", "description": "memoryType of the survivor. Defaults to \"memory\" for a newly created survivor." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Extra metadata for the survivor, merged over its existing metadata. The merge bookkeeping keys (mergedFromIds, mergedAt) always win." }, "mergeKey": { "type": "string", "example": "inbox-merge-2026-09-02-7", "maxLength": 200, "description": "Natural idempotency key of this merge. Defaults to a hash of the sorted ids. Replaying a completed merge returns its survivor with replayed=true." } }, "required": ["ids"] }, "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"] }, "MemoryProvenanceDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["api_key", "mcp", "user", "connector", "inbound", "system"], "example": "api_key", "description": "api_key | mcp | user | connector | inbound | system. Memories written before provenance stamping have createdBy = null." }, "id": { "type": "string", "nullable": true, "description": "API key id, MCP grant id, user id, connector connection id or inbound channel id; null for system writes." }, "label": { "type": "string", "nullable": true, "example": "Chrome extension", "description": "Short human label: API key name, MCP client name, connector provider slug, \"whatsapp\"/\"sms\", \"ingestion\"." } }, "required": ["kind", "id", "label"] }, "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 }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Reminder due time; non-null only for open reminders (memoryType \"reminder\")." }, "createdBy": { "nullable": true, "description": "Server-stamped write provenance. null for memories written before provenance stamping.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MemoryProvenanceDto" } ] } }, "required": [ "id", "scopeKey", "scope", "container", "content", "contentHash", "idempotencyKey", "memoryType", "mutationPolicy", "protectedAt", "metadata", "source", "sourceDocumentId", "eventId", "createdAt", "updatedAt", "deletedAt", "dueAt", "createdBy" ] }, "MergeMemoriesResponseDto": { "type": "object", "properties": { "memory": { "description": "The surviving memory.", "allOf": [ { "$ref": "#/components/schemas/MemoryRecordDto" } ] }, "mergedFromIds": { "description": "Source ids folded into the survivor by this merge.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "deletedIds": { "description": "Source ids soft-deleted (restorable) by this merge.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "replayed": { "type": "boolean", "description": "true when this request replayed an already-completed merge with the same mergeKey and nothing new was written." } }, "required": ["memory", "mergedFromIds", "deletedIds", "replayed"] }, "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 }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Reminder due time. Omit to leave unchanged; null clears it (completing a reminder); a date-time requires the memory to be a \"reminder\" (400 NOT_A_REMINDER otherwise)." } } }, "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" ] }, "AnswerRequestDto": { "type": "object", "properties": { "scope": { "description": "Primary scope object. Preferred over containerTag for public API usage. Name at least one of scope, scopes, containerTag or containerTags; a request with none is rejected. scope.tags is accepted but not used by this endpoint.", "allOf": [ { "$ref": "#/components/schemas/ScopeDto" } ] }, "containerTag": { "type": "string", "example": "user:alice", "description": "Deprecated shorthand alias for scope, in the form :.", "deprecated": true }, "q": { "type": "string", "example": "What did I save about pricing?", "description": "The natural-language question to answer." }, "scopes": { "description": "Answer across several scopes at once. Combined with scope and containerTag(s); duplicates are ignored. A tags array on each entry is accepted but not used by this endpoint.", "type": "array", "items": { "$ref": "#/components/schemas/ScopeDto" } }, "containerTags": { "example": ["user:alice", "project:alpha"], "description": "Deprecated shorthand alias for scopes, each in the form :.", "deprecated": true, "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "description": "Most retrieval candidates to consider. The server may adjust it, and picks its own when omitted. Ignored when mode is fast.", "minimum": 1, "maximum": 50 }, "includeCitations": { "type": "boolean", "description": "Return the top retrieved snippets (at most 10) as citations. Set false to omit them.", "default": true }, "agentic": { "type": "boolean", "description": "Thorough, iterative retrieval, at the cost of latency. On by default in full mode; set false for a quicker pass. The server may ignore it, and always does when mode is fast." }, "referenceDate": { "type": "string", "example": "2026-04-16", "description": "Date (YYYY-MM-DD) treated as today for relative-time questions such as \"two weeks ago\". Defaults to a date inferred from the documents in scope, otherwise the current UTC date. Pass YYYY-MM-DD; other strings are accepted but can give wrong relative-time answers." }, "mode": { "type": "string", "description": "`full` (default) runs the deeper multi-step pipeline: slower and more thorough. `fast` is the lower-latency path and ignores limit and agentic; it can still hand a harder question to the deeper pipeline.", "enum": ["fast", "full"], "default": "full" } }, "required": ["q"] }, "AnswerStatsDto": { "type": "object", "properties": { "searchResults": { "type": "integer", "description": "Approximate count of the evidence items considered, usually retrieval hits." }, "latencyMs": { "type": "integer", "description": "Server-side processing time in milliseconds." } }, "required": ["searchResults", "latencyMs"] }, "AnswerResponseDto": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer, written from the memories in scope. When nothing in scope matches, it usually tells you so, but a retry can return a best-effort answer instead, so check it against the citations. The wording varies, so don't match on exact text; there's no separate abstention field." }, "citations": { "description": "The top retrieved snippets, up to 10, in ranked order. The answer may also draw on evidence that isn't listed, so this isn't a per-claim attribution, and they can come back even when the answer says it doesn't know. Returned by default but may be empty or absent; always absent when includeCitations is false.", "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/AnswerCitationDto" } }, "stats": { "$ref": "#/components/schemas/AnswerStatsDto" } }, "required": ["answer", "stats"], "description": "The answer to the question. The response may include other informational fields; ignore any you don't recognise." }, "AnswerCitationDto": { "type": "object", "properties": { "type": { "type": "string", "example": "memory", "description": "Kind of record the snippet came from: memory, document, or fact." }, "score": { "type": "number", "description": "Retrieval score." }, "content": { "type": "string", "description": "The snippet text." }, "sourceId": { "type": "string", "description": "Id of the cited memory, document or fact." }, "title": { "type": "string", "description": "Source title, when the record has one (up to 200 characters)." }, "url": { "type": "string", "description": "Absolute http(s) link to the source, when the record has one." } }, "required": ["type", "score", "content"] }, "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" ] }, "PersonImportantDateDto": { "type": "object", "properties": { "label": { "type": "string", "example": "Birthday", "maxLength": 60 }, "date": { "type": "string", "example": "1990-05-01", "description": "Calendar date, YYYY-MM-DD." }, "recurring": { "type": "boolean", "example": true, "description": "Recurs every year on the same month and day (birthdays, anniversaries)." } }, "required": ["label", "date", "recurring"] }, "CreatePersonDto": { "type": "object", "properties": { "relationship": { "type": "object", "example": "friend", "maxLength": 80, "nullable": true }, "email": { "type": "object", "example": "alice@example.com", "nullable": true }, "phone": { "type": "object", "example": "+15551234567", "nullable": true, "description": "E.164; cosmetic spaces, dashes and parentheses are stripped." }, "company": { "type": "object", "example": "Acme", "maxLength": 120, "nullable": true }, "notes": { "type": "object", "maxLength": 4000, "nullable": true }, "importantDates": { "maxItems": 20, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/PersonImportantDateDto" } }, "aliases": { "example": ["Al"], "maxItems": 10, "nullable": true, "type": "array", "items": { "type": "string" } }, "displayName": { "type": "string", "example": "Alice Smith", "maxLength": 120 }, "slug": { "type": "string", "example": "alice-smith", "maxLength": 64, "description": "Explicit slug (lowercase alphanumerics and single hyphens). Derived from displayName when omitted; immutable after create." } }, "required": ["displayName"] }, "PersonDto": { "type": "object", "properties": { "slug": { "type": "string", "example": "alice-smith" }, "tag": { "type": "string", "example": "person:alice-smith" }, "containerId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "example": "Alice Smith" }, "relationship": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "company": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "importantDates": { "type": "array", "items": { "$ref": "#/components/schemas/PersonImportantDateDto" } }, "aliases": { "type": "array", "items": { "type": "string" } }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "memoryCount": { "type": "integer", "description": "Live memories in the person container." }, "openReminderCount": { "type": "integer", "description": "Open reminders in the person container." }, "nextReminderAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "slug", "tag", "containerId", "displayName", "relationship", "email", "phone", "company", "notes", "importantDates", "aliases", "archivedAt", "memoryCount", "openReminderCount", "nextReminderAt", "createdAt", "updatedAt" ] }, "ListPeopleResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonDto" } }, "nextCursor": { "type": "string", "nullable": true }, "total": { "type": "integer" } }, "required": ["items", "nextCursor", "total"] }, "UpdatePersonDto": { "type": "object", "properties": { "relationship": { "type": "object", "example": "friend", "maxLength": 80, "nullable": true }, "email": { "type": "object", "example": "alice@example.com", "nullable": true }, "phone": { "type": "object", "example": "+15551234567", "nullable": true, "description": "E.164; cosmetic spaces, dashes and parentheses are stripped." }, "company": { "type": "object", "example": "Acme", "maxLength": 120, "nullable": true }, "notes": { "type": "object", "maxLength": 4000, "nullable": true }, "importantDates": { "maxItems": 20, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/PersonImportantDateDto" } }, "aliases": { "example": ["Al"], "maxItems": 10, "nullable": true, "type": "array", "items": { "type": "string" } }, "displayName": { "type": "string", "example": "Alice Smith", "maxLength": 120 }, "archived": { "type": "boolean", "description": "true archives the person (hidden from lists and reads); false restores them." } } }, "ArchivePersonResponseDto": { "type": "object", "properties": { "slug": { "type": "string", "example": "alice-smith" }, "archived": { "type": "boolean", "enum": [true] }, "memoriesDeleted": { "type": "integer" } }, "required": ["slug", "archived", "memoriesDeleted"] }, "PersonSummaryCitationDto": { "type": "object", "properties": { "type": { "type": "string", "example": "memory" }, "score": { "type": "number" }, "content": { "type": "string" }, "sourceId": { "type": "string", "description": "Id of the cited memory, document or fact." }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": ["type", "score", "content"] }, "ReminderPersonDto": { "type": "object", "properties": { "slug": { "type": "string", "example": "alice-smith" }, "displayName": { "type": "string", "example": "Alice Smith" } }, "required": ["slug", "displayName"] }, "ReminderDto": { "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 }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Reminder due time; non-null only for open reminders (memoryType \"reminder\")." }, "createdBy": { "nullable": true, "description": "Server-stamped write provenance. null for memories written before provenance stamping.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MemoryProvenanceDto" } ] }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "person": { "nullable": true, "description": "The person the reminder is filed under, when its container is a person.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReminderPersonDto" } ] } }, "required": [ "id", "scopeKey", "scope", "container", "content", "contentHash", "idempotencyKey", "memoryType", "mutationPolicy", "protectedAt", "metadata", "source", "sourceDocumentId", "eventId", "createdAt", "updatedAt", "deletedAt", "dueAt", "createdBy", "completedAt", "person" ] }, "PersonSummaryDto": { "type": "object", "properties": { "slug": { "type": "string", "example": "alice-smith" }, "answer": { "type": "string", "description": "Reader answer; empty when abstained." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSummaryCitationDto" } }, "abstained": { "type": "boolean", "description": "true when nothing in the person's memories answers the question, or the reader did not respond within the time budget." }, "openReminders": { "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "recentMemories": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordDto" } } }, "required": ["slug", "answer", "citations", "abstained", "openReminders", "recentMemories"] }, "CreateReminderDto": { "type": "object", "properties": { "content": { "type": "string", "example": "Send Alice the proposal", "maxLength": 4000 }, "dueAt": { "type": "string", "format": "date-time", "example": "2026-09-15T09:00:00Z" }, "personSlug": { "type": "string", "example": "alice-smith", "description": "File the reminder in this person's container. Exactly one of personSlug, containerTag or scope is required." }, "containerTag": { "type": "string", "example": "project:alpha", "description": "Any container tag." }, "scope": { "$ref": "#/components/schemas/ScopeDto" }, "idempotencyKey": { "type": "string", "example": "crm-followup-42", "description": "Natural idempotency key, unique per container; a repeat returns the existing reminder." }, "metadata": { "type": "object", "additionalProperties": true } }, "required": ["content", "dueAt"] }, "ListRemindersResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "nextCursor": { "type": "string", "nullable": true }, "total": { "type": "integer" } }, "required": ["items", "nextCursor", "total"] }, "ImportantDateDto": { "type": "object", "properties": { "personSlug": { "type": "string", "example": "alice-smith" }, "displayName": { "type": "string", "example": "Alice Smith" }, "label": { "type": "string", "example": "Birthday" }, "date": { "type": "string", "example": "2026-05-01", "description": "The occurrence inside the window, YYYY-MM-DD." }, "daysUntil": { "type": "integer", "description": "Days from today (in the requested timezone) to the occurrence." }, "recurring": { "type": "boolean" } }, "required": ["personSlug", "displayName", "label", "date", "daysUntil", "recurring"] }, "UpcomingRemindersResponseDto": { "type": "object", "properties": { "overdue": { "description": "Due before today (local day).", "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "dueToday": { "description": "Due within today (local day).", "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "upcoming": { "description": "Due after today, within the window.", "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "importantDates": { "type": "array", "items": { "$ref": "#/components/schemas/ImportantDateDto" } }, "generatedAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "example": "UTC" } }, "required": ["overdue", "dueToday", "upcoming", "importantDates", "generatedAt", "timezone"] }, "UpdateReminderDto": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 4000 }, "dueAt": { "type": "string", "format": "date-time", "description": "Reschedule. Use /complete to close a reminder." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Merged into the stored metadata; completedAt / originalDueAt are managed by the server." } } }, "ReopenReminderDto": { "type": "object", "properties": { "dueAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:00:00Z" } }, "required": ["dueAt"] }, "TimelineItemMetaDto": { "type": "object", "properties": { "memoryType": { "type": "string", "example": "reminder", "description": "memory | reminder rows" }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Reminder due time (memory | reminder rows)." }, "contentType": { "type": "string", "example": "text/plain", "description": "document rows" }, "provider": { "type": "string", "example": "google_calendar", "description": "Connector provider slug for connector-synced documents." }, "status": { "type": "string", "example": "completed", "description": "Document ingestion status." }, "itemUpdatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Source-side last-modified stamp of a connector-synced document, when the provider reported one." }, "eventType": { "type": "string", "example": "memory_deleted", "description": "event rows" }, "actorId": { "type": "string", "nullable": true, "description": "event rows" }, "documentId": { "type": "string", "format": "uuid", "description": "The source document this row is, or was extracted from." }, "memoryId": { "type": "string", "format": "uuid", "description": "The memory this row is (memory | reminder rows)." } } }, "TimelineItemDto": { "type": "object", "properties": { "id": { "type": "string", "example": "memory:1d1c6d8e-8a3e-4b1a-9d26-7d4f3f9e0a11", "description": "Composite id `${type}:${refId}`, unique within the stream." }, "type": { "type": "string", "enum": ["memory", "reminder", "document", "event"], "example": "memory" }, "refId": { "type": "string", "format": "uuid", "description": "Underlying memory / document / event id." }, "occurredAt": { "type": "string", "format": "date-time" }, "title": { "type": "string", "example": "Alice prefers Monday updates.", "description": "memory: first 120 chars; document: metadata title, calendar summary or contentType; event: title or eventType." }, "snippet": { "type": "string", "nullable": true, "description": "Up to 280 chars of body text." }, "containerTag": { "type": "string", "example": "user:alice" }, "createdBy": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MemoryProvenanceDto" } ] }, "meta": { "$ref": "#/components/schemas/TimelineItemMetaDto" } }, "required": [ "id", "type", "refId", "occurredAt", "title", "snippet", "containerTag", "createdBy", "meta" ] }, "TimelineContainerDto": { "type": "object", "properties": { "tag": { "type": "string", "example": "user:alice" }, "containerType": { "type": "string", "example": "user" }, "displayName": { "type": "string", "nullable": true } }, "required": ["tag", "containerType", "displayName"] }, "TimelineRangeDto": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["from", "to"] }, "TimelineResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineItemDto" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when this is the last page." }, "container": { "nullable": true, "description": "The resolved container, or null when no such container exists yet (items is then empty).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimelineContainerDto" } ] }, "range": { "$ref": "#/components/schemas/TimelineRangeDto" } }, "required": ["items", "nextCursor", "container", "range"] }, "CreateInboundChannelDto": { "type": "object", "properties": { "phone": { "type": "string", "example": "+14155552671", "description": "Phone number that will send notes, in E.164. Cosmetic spaces, dashes and parentheses are stripped." }, "containerTag": { "type": "string", "example": "user:alice", "description": "Container that receives every captured note. Defaults to `phone:`." }, "scope": { "description": "Scope object alternative to containerTag.", "allOf": [ { "$ref": "#/components/schemas/ScopeDto" } ] } }, "required": ["phone"] }, "InboundChannelDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "example": "twilio" }, "phoneMasked": { "type": "string", "example": "+1••••••2671", "description": "Masked sender number. The full number is never returned." }, "containerTag": { "type": "string", "example": "user:alice" }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": ["pending", "active", "disabled"] }, "verificationCode": { "type": "string", "example": "482913", "description": "Six-digit verification code the phone must send to activate the channel. Returned in plaintext ONLY by create and regenerate-code." }, "verifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastMessageAt": { "type": "string", "format": "date-time", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "example": "https://api.mnemohq.com/v1/inbound/twilio", "description": "Messaging webhook URL to paste into the Twilio console." }, "inboundNumber": { "type": "string", "nullable": true, "description": "SMS number to text." }, "whatsappSender": { "type": "string", "nullable": true, "description": "WhatsApp sender number." }, "sandboxJoinWord": { "type": "string", "nullable": true, "description": "Join word for the Twilio WhatsApp sandbox, when a sandbox sender is in use." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "provider", "phoneMasked", "containerTag", "userId", "status", "verifiedAt", "lastMessageAt", "webhookUrl", "inboundNumber", "whatsappSender", "sandboxJoinWord", "createdAt" ] }, "ListInboundChannelsResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InboundChannelDto" } }, "nextCursor": { "type": "string", "nullable": true }, "total": { "type": "number", "example": 1 } }, "required": ["items", "nextCursor", "total"] }, "UpdateInboundChannelDto": { "type": "object", "properties": { "containerTag": { "type": "string", "example": "user:alice" }, "status": { "type": "string", "enum": ["active", "disabled"], "description": "Disable or re-enable a channel. A pending channel cannot be activated here — it activates when the phone sends its verification code." } } }, "DeleteInboundChannelResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "example": true } }, "required": ["id", "deleted"] }, "MeetingOrganizerDto": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "required": ["email", "name"] }, "MeetingPersonRefDto": { "type": "object", "properties": { "slug": { "type": "string", "example": "alice-smith" }, "displayName": { "type": "string", "example": "Alice Smith" } }, "required": ["slug", "displayName"] }, "MeetingAttendeeDto": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "example": "alice@example.com" }, "name": { "type": "string", "nullable": true, "example": "Alice Smith" }, "responseStatus": { "type": "string", "nullable": true, "example": "accepted", "description": "Google responseStatus: needsAction | declined | tentative | accepted. Null for legacy documents." }, "self": { "type": "boolean", "description": "true when this attendee is the calendar owner." }, "person": { "nullable": true, "description": "The workspace person whose stored email matches this attendee, when one exists.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MeetingPersonRefDto" } ] } }, "required": ["email", "name", "responseStatus", "self", "person"] }, "MeetingDto": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "SourceDocument id of the calendar event." }, "eventId": { "type": "string", "nullable": true, "description": "Google Calendar event id." }, "title": { "type": "string", "example": "Roadmap sync" }, "start": { "type": "string", "nullable": true, "description": "RFC3339 date-time for timed events, YYYY-MM-DD for all-day events.", "example": "2026-09-03T14:00:00-04:00" }, "end": { "type": "string", "nullable": true, "description": "RFC3339 date-time, or the EXCLUSIVE end date (day after the last day) for all-day events." }, "isAllDay": { "type": "boolean" }, "status": { "type": "string", "nullable": true, "example": "confirmed", "description": "confirmed | tentative." }, "htmlLink": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "organizer": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MeetingOrganizerDto" } ] }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingAttendeeDto" } }, "containerTag": { "type": "string", "example": "calendar:me@example.com", "description": "The connection's container tag." }, "connectionId": { "type": "string", "format": "uuid", "nullable": true }, "attendeeSource": { "type": "string", "enum": ["metadata", "contentText", "none"], "description": "Where attendees came from: structured metadata (documents synced on v0.9+), the Who: line of an older document, or nowhere." } }, "required": [ "documentId", "eventId", "title", "start", "end", "isAllDay", "status", "htmlLink", "location", "organizer", "attendees", "containerTag", "connectionId", "attendeeSource" ] }, "MeetingConnectionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "containerTag": { "type": "string", "example": "calendar:me@example.com" }, "status": { "type": "string", "example": "active", "description": "pending | active | paused | error | revoked." }, "lastSyncAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["id", "containerTag", "status", "lastSyncAt"] }, "ListUpcomingMeetingsResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingDto" } }, "nextCursor": { "type": "string", "nullable": true }, "connections": { "description": "Google Calendar connections in the workspace; empty when none is connected.", "type": "array", "items": { "$ref": "#/components/schemas/MeetingConnectionDto" } } }, "required": ["items", "nextCursor", "connections"] }, "MeetingBriefAnswerDto": { "type": "object", "properties": { "answer": { "type": "string", "description": "Reader answer; empty when abstained." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSummaryCitationDto" } }, "abstained": { "type": "boolean", "description": "true when the memories do not answer the briefing question." }, "cached": { "type": "boolean", "description": "true when served from the 15-minute brief cache." } }, "required": ["answer", "citations", "abstained", "cached"] }, "MeetingBriefPersonDto": { "type": "object", "properties": { "slug": { "type": "string", "example": "alice-smith" }, "displayName": { "type": "string", "example": "Alice Smith" }, "relationship": { "type": "string", "nullable": true }, "openReminders": { "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "recentMemories": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordDto" } } }, "required": ["slug", "displayName", "relationship", "openReminders", "recentMemories"] }, "PreviousMeetingDto": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "Roadmap sync" }, "start": { "type": "string", "nullable": true } }, "required": ["documentId", "title", "start"] }, "MeetingBriefDto": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "SourceDocument id of the calendar event." }, "eventId": { "type": "string", "nullable": true, "description": "Google Calendar event id." }, "title": { "type": "string", "example": "Roadmap sync" }, "start": { "type": "string", "nullable": true, "description": "RFC3339 date-time for timed events, YYYY-MM-DD for all-day events.", "example": "2026-09-03T14:00:00-04:00" }, "end": { "type": "string", "nullable": true, "description": "RFC3339 date-time, or the EXCLUSIVE end date (day after the last day) for all-day events." }, "isAllDay": { "type": "boolean" }, "status": { "type": "string", "nullable": true, "example": "confirmed", "description": "confirmed | tentative." }, "htmlLink": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "organizer": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/MeetingOrganizerDto" } ] }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingAttendeeDto" } }, "containerTag": { "type": "string", "example": "calendar:me@example.com", "description": "The connection's container tag." }, "connectionId": { "type": "string", "format": "uuid", "nullable": true }, "attendeeSource": { "type": "string", "enum": ["metadata", "contentText", "none"], "description": "Where attendees came from: structured metadata (documents synced on v0.9+), the Who: line of an older document, or nowhere." }, "brief": { "nullable": true, "description": "Null when the reader did not respond within the time budget or failed; the other sections still render.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/MeetingBriefAnswerDto" } ] }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingBriefPersonDto" } }, "previousMeetings": { "description": "Up to 5 past meetings sharing at least one attendee, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/PreviousMeetingDto" } }, "generatedAt": { "type": "string", "format": "date-time" } }, "required": [ "documentId", "eventId", "title", "start", "end", "isAllDay", "status", "htmlLink", "location", "organizer", "attendees", "containerTag", "connectionId", "attendeeSource", "brief", "people", "previousMeetings", "generatedAt" ] }, "BriefScopeDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workspace", "container"] }, "containerTag": { "type": "string", "nullable": true, "example": "user:alice" } }, "required": ["kind", "containerTag"] }, "BriefRemindersDto": { "type": "object", "properties": { "overdue": { "description": "Due before the briefed day.", "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "dueToday": { "description": "Due on the briefed day.", "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } }, "upcoming": { "description": "Due after the briefed day, within `days`.", "type": "array", "items": { "$ref": "#/components/schemas/ReminderDto" } } }, "required": ["overdue", "dueToday", "upcoming"] }, "BriefCountsDto": { "type": "object", "properties": { "memoriesLast24h": { "type": "integer", "description": "Memories written in the 24h before the briefed day plus the day itself." }, "documentsLast24h": { "type": "integer", "description": "Documents ingested in the same window." } }, "required": ["memoriesLast24h", "documentsLast24h"] }, "BriefFollowUpsDto": { "type": "object", "properties": { "answer": { "type": "string", "description": "Reader answer; empty when abstained." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSummaryCitationDto" } }, "abstained": { "type": "boolean", "description": "true when nothing outstanding could be found." }, "cached": { "type": "boolean", "description": "true when served from the 30-minute follow-ups cache." } }, "required": ["answer", "citations", "abstained", "cached"] }, "DailyBriefDto": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-09-02", "description": "The briefed local day." }, "timezone": { "type": "string", "example": "UTC" }, "generatedAt": { "type": "string", "format": "date-time" }, "scope": { "$ref": "#/components/schemas/BriefScopeDto" }, "reminders": { "nullable": true, "description": "Null unless the core section was requested.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BriefRemindersDto" } ] }, "importantDates": { "nullable": true, "description": "Null unless the core section was requested.", "type": "array", "items": { "$ref": "#/components/schemas/ImportantDateDto" } }, "recentMemories": { "nullable": true, "description": "Newest non-reminder memories of the window (max 20). Null unless the core section was requested.", "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordDto" } }, "counts": { "nullable": true, "description": "Null unless the core section was requested.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BriefCountsDto" } ] }, "followUps": { "nullable": true, "description": "Promises and open follow-ups from the fast reader. Null when not requested, or when the reader did not respond within the time budget.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BriefFollowUpsDto" } ] }, "meetings": { "nullable": true, "description": "Today's meetings. Null when not requested, when MEMORY_API_MEETINGS_ENABLED is off, or when no calendar is connected.", "type": "array", "items": { "$ref": "#/components/schemas/MeetingDto" } } }, "required": [ "date", "timezone", "generatedAt", "scope", "reminders", "importantDates", "recentMemories", "counts", "followUps", "meetings" ] } } } }