From 193d8840e807b296410e87291ca91a9f2de56a8f Mon Sep 17 00:00:00 2001 From: Robert Shelton Date: Fri, 30 Oct 2026 08:29:48 -0400 Subject: [PATCH 1/4] Iris docs: refresh the Iris OpenAPI references from the unified API contracts Regenerated from redislabsdev/iris main (81f2e7a0c) Smithy public projections, following each product's publish workflow: Agent Memory data plane (with the published overlay), Agent Memory self-managed control plane (shared /v2 contract merged with the on-prem ingestion-hooks contract, cloud-only elements prefixed), Agent Playbooks data plane, and Lens data plane (v1beta1). The Context Gateway control-plane spec is left to redis/docs#4358. Co-Authored-By: Claude Opus 5.5 --- .../api-reference/openapi-agent-memory.json | 2209 +++--- .../api-reference/openapi.json | 3969 ++++++---- .../lens/api-reference/openapi.json | 218 +- .../openapi-control-plane.json | 6457 +++++++++++------ 4 files changed, 7908 insertions(+), 4945 deletions(-) diff --git a/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json b/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json index 8ae68ff124..f8bbadc03b 100644 --- a/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json +++ b/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json @@ -3,10 +3,10 @@ "info": { "title": "Redis Agent Memory API", "version": "1.0.0", - "description": "API for storing, retrieving, and searching Redis Agent Memory session memory and long-term memory.\n\nAuthentication depends on your deployment. Use the credential issued for your Redis Agent Memory service or store. For self-managed deployments, see the self-managed Redis Agent Memory guide for authentication options.\n" + "description": "API for storing, retrieving, and searching Redis Agent Memory session memory and long-term memory.\n\nAuthentication depends on your deployment. Use the credential issued for your Agent Memory service or store. For self-managed deployments, see the self-managed Agent Memory guide for authentication options.\n" }, "paths": { - "/v1/stores/{storeId}/document-ingestions": { + "/iris/data/v1/agent-memory/stores/{storeId}/document-ingestions": { "post": { "description": "Submit one revisioned document for extraction.", "operationId": "CreateDocumentIngestion", @@ -24,13 +24,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true } @@ -145,11 +145,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -187,33 +187,33 @@ } } }, - "/v1/stores/{storeId}/document-ingestions/{ingestionId}": { + "/iris/data/v1/agent-memory/stores/{storeId}/document-ingestions/{ingestionId}": { "get": { "operationId": "GetDocumentIngestion", "parameters": [ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "ingestionId", "in": "path", - "description": "Server-generated document ingestion identifier.", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated document ingestion identifier." + "maxLength": 36, + "minLength": 36, + "pattern": "^ing_[0-9a-f]{32}$", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters." }, "required": true } @@ -312,50 +312,57 @@ } } }, - "/v1/stores/{storeId}/document-ingestions/{ingestionId}/outputs": { + "/iris/data/v1/agent-memory/stores/{storeId}/document-ingestions/{ingestionId}/outputs": { "get": { "operationId": "ListDocumentIngestionOutputs", "parameters": [ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "ingestionId", "in": "path", - "description": "Server-generated document ingestion identifier.", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated document ingestion identifier." + "maxLength": 36, + "minLength": 36, + "pattern": "^ing_[0-9a-f]{32}$", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "limit", "in": "query", + "description": "Maximum number of memory IDs to return. Defaults to 50. Allowed range: 1-100.", "schema": { "type": "integer", + "maximum": 100, + "minimum": 1, + "description": "Maximum number of memory IDs to return. Defaults to 50. Allowed range: 1-100.", "format": "int32" } }, { - "name": "offset", + "name": "cursor", "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "integer", - "format": "int32" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } } ], @@ -453,9 +460,9 @@ } } }, - "/v1/stores/{storeId}/health": { + "/iris/data/v1/agent-memory/stores/{storeId}/health": { "get": { - "description": "Returns read-only health for applicable store-scoped RAM features.", + "description": "Returns read-only health for applicable store-scoped Agent Memory features.", "operationId": "StoreHealth", "parameters": [ { @@ -464,9 +471,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -589,21 +596,21 @@ ] } }, - "/v1/stores/{storeId}/ingestion-hooks/events": { + "/iris/data/v1/agent-memory/stores/{storeId}/ingestion-hook-events": { "get": { - "description": "List hook decisions in stable newest-first order. Pages can be empty after owner filtering; continue while nextCursor is present. Internal run reservations are omitted.", + "description": "List hook decisions in stable newest-first order. Pages can be empty after owner filtering; continue while nextCursor is present.", "operationId": "ListIngestionHookStatuses", "parameters": [ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, @@ -621,8 +628,12 @@ { "name": "cursor", "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } } ], @@ -678,11 +689,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -703,7 +714,7 @@ ] } }, - "/v1/stores/{storeId}/ingestion-hooks/events/{eventId}": { + "/iris/data/v1/agent-memory/stores/{storeId}/ingestion-hook-events/{eventId}": { "get": { "description": "Read a hook decision and application status. Requires authenticated store access and, when enforced, matching owner scope. Content and secrets are never returned.", "operationId": "GetIngestionHookStatus", @@ -711,13 +722,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, @@ -792,11 +803,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -817,15 +828,15 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory": { - "delete": { - "description": "Deletes long-term memories in bulk by their IDs.", - "operationId": "BulkDeleteLongTermMemories", + "/iris/data/v1/agent-memory/stores/{storeId}/memories": { + "post": { + "description": "Creates long-term memories in bulk. A memoryId that already exists is rejected for that record (reported in errors) and the stored memory is left unchanged; change a memory with UpdateLongTermMemory. Records without namespaceId stay un-namespaced. Automatic routing does not place them in a shared namespace. An explicit namespaceId must pass destination admission and is never rerouted. Admission failures are reported per record in errors.", + "operationId": "BulkCreateLongTermMemories", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BulkDeleteLongTermMemoriesRequestContent" + "$ref": "#/components/schemas/BulkCreateLongTermMemoriesRequestContent" } } }, @@ -838,21 +849,21 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true } ], "responses": { - "200": { - "description": "BulkDeleteLongTermMemories 200 response", + "201": { + "description": "BulkCreateLongTermMemories 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BulkDeleteLongTermMemoriesResponseContent" + "$ref": "#/components/schemas/BulkCreateLongTermMemoriesResponseContent" } } } @@ -917,6 +928,16 @@ } } }, + "422": { + "description": "IngestionHookStoppedError 422 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IngestionHookStoppedErrorResponseContent" + } + } + } + }, "423": { "description": "ResourceSuspendedError 423 response", "content": { @@ -956,20 +977,32 @@ } } } + }, + "503": { + "description": "IngestionHookRetryError 503 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IngestionHookRetryErrorResponseContent" + } + } + } } }, "tags": [ "Long-Term Memory" ] - }, + } + }, + "/iris/data/v1/agent-memory/stores/{storeId}/memories/bulk-delete": { "post": { - "description": "Creates long-term memories in bulk. Records without namespace or namespaceRef stay un-namespaced. Automatic routing does not place them in a shared namespace. An explicit namespaceRef must pass destination admission and is never rerouted. Admission failures are reported per record in errors.", - "operationId": "BulkCreateLongTermMemories", + "description": "Deletes long-term memories in bulk by their IDs.", + "operationId": "BulkDeleteLongTermMemories", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BulkCreateLongTermMemoriesRequestContent" + "$ref": "#/components/schemas/BulkDeleteLongTermMemoriesRequestContent" } } }, @@ -982,21 +1015,21 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true } ], "responses": { - "201": { - "description": "BulkCreateLongTermMemories 201 response", + "200": { + "description": "BulkDeleteLongTermMemories 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BulkCreateLongTermMemoriesResponseContent" + "$ref": "#/components/schemas/BulkDeleteLongTermMemoriesResponseContent" } } } @@ -1061,16 +1094,6 @@ } } }, - "422": { - "description": "IngestionHookStoppedError 422 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IngestionHookStoppedErrorResponseContent" - } - } - } - }, "423": { "description": "ResourceSuspendedError 423 response", "content": { @@ -1082,11 +1105,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -1110,16 +1133,6 @@ } } } - }, - "503": { - "description": "IngestionHookRetryError 503 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IngestionHookRetryErrorResponseContent" - } - } - } } }, "tags": [ @@ -1127,9 +1140,9 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory/move": { + "/iris/data/v1/agent-memory/stores/{storeId}/memories/move": { "post": { - "description": "Moves long-term memories to an explicit namespaceRef, or automatically routes a memory that is already in a shared namespace when namespaceRef is omitted. Personal and un-namespaced memories are not automatic-routing candidates and keep their current placement with a per-item error. If routing is disabled or no shared destination qualifies, the memory also keeps its current placement and receives a per-item error. An explicit destination must pass admission and is never rerouted. Returns 409 when the explicit destination is archived; automatic routing and admission failures are reported per item in errors.", + "description": "Moves long-term memories to an explicit namespaceId, or automatically routes a memory that is already in a shared namespace when namespaceId is omitted. Personal and un-namespaced memories are not automatic-routing candidates and keep their current placement with a per-item error. If routing is disabled or no shared destination qualifies, the memory also keeps its current placement and receives a per-item error. An explicit destination must pass admission and is never rerouted. Returns 409 when the explicit destination is archived; automatic routing and admission failures are reported per item in errors.", "operationId": "MoveLongTermMemories", "requestBody": { "content": { @@ -1145,13 +1158,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true } @@ -1283,7 +1296,7 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory/search": { + "/iris/data/v1/agent-memory/stores/{storeId}/memories/search": { "post": { "description": "Runs a semantic search on long-term memory with filtering options.", "operationId": "SearchLongTermMemory", @@ -1303,9 +1316,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -1393,11 +1406,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -1428,7 +1441,7 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory/{memoryId}": { + "/iris/data/v1/agent-memory/stores/{storeId}/memories/{memoryId}": { "get": { "description": "Returns a long-term memory by its ID.", "operationId": "GetLongTermMemory", @@ -1439,9 +1452,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -1454,7 +1467,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The memory record ID." }, "required": true @@ -1595,9 +1608,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -1610,7 +1623,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The memory record ID." }, "required": true @@ -1708,11 +1721,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -1743,9 +1756,9 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory/{memoryId}/fields": { + "/iris/data/v1/agent-memory/stores/{storeId}/memories/{memoryId}/fields": { "patch": { - "description": "Atomically updates a custom-typed long-term memory's text and/or attributes, scoped to the caller's bound memory type. Used by the custom-extraction worker. New text must pass destination admission before the update is applied.", + "description": "Atomically updates a custom-typed long-term memory's text and/or attributes, scoped to the caller's bound memory type. New text must pass destination admission before the update is applied.", "operationId": "UpdateLongTermMemoryFields", "requestBody": { "content": { @@ -1764,9 +1777,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -1779,7 +1792,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The memory record ID." }, "required": true @@ -1860,11 +1873,11 @@ } }, "424": { - "description": "MemoryFailedDependencyError 424 response", + "description": "FailedDependencyError 424 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" } } } @@ -1895,7 +1908,7 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory/{memoryId}/sources": { + "/iris/data/v1/agent-memory/stores/{storeId}/memories/{memoryId}/sources": { "get": { "description": "Pages source links for one long-term memory. Tokens bind this query and expire.", "operationId": "ListMemorySourceLinks", @@ -1903,26 +1916,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "memoryId", "in": "path", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation.", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "required": true }, @@ -1937,10 +1950,14 @@ } }, { - "name": "pageToken", + "name": "cursor", "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } } ], @@ -2041,7 +2058,7 @@ ] } }, - "/v1/stores/{storeId}/long-term-memory/{memoryId}/sources/{sourceId}/evidence": { + "/iris/data/v1/agent-memory/stores/{storeId}/memories/{memoryId}/sources/{sourceId}/evidence": { "get": { "description": "Pages extraction evidence for one source of a memory, in append order. Tokens bind the store, current owner, memory and source, and expire.", "operationId": "ListMemorySourceEvidence", @@ -2049,26 +2066,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "memoryId", "in": "path", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation.", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "required": true }, @@ -2096,10 +2113,14 @@ } }, { - "name": "pageToken", + "name": "cursor", "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } } ], @@ -2200,7 +2221,7 @@ ] } }, - "/v1/stores/{storeId}/namespace-routing": { + "/iris/data/v1/agent-memory/stores/{storeId}/namespace-routing": { "get": { "description": "Returns the store's namespace routing policy. An empty disabled policy is returned when none has been saved.", "operationId": "GetNamespaceRouting", @@ -2208,13 +2229,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true } @@ -2336,7 +2357,7 @@ ] }, "put": { - "description": "Replaces the store's namespace routing policy. Namespaces remain hierarchy records; routing is an ordered store-level document of plug-in strategies.", + "description": "Replaces the store's namespace routing policy.", "operationId": "PutNamespaceRouting", "requestBody": { "content": { @@ -2352,13 +2373,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true } @@ -2490,7 +2511,7 @@ ] } }, - "/v1/stores/{storeId}/namespaces": { + "/iris/data/v1/agent-memory/stores/{storeId}/namespaces": { "get": { "description": "Lists namespace roots or direct children.", "operationId": "ListNamespaces", @@ -2498,13 +2519,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, @@ -2514,9 +2535,9 @@ "description": "List direct children of this namespace. Omit to list roots.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", "description": "List direct children of this namespace. Omit to list roots." } }, @@ -2536,7 +2557,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Restrict personal root results to an owner. Cannot be combined with parentId; ignored for shared roots." } }, @@ -2559,22 +2580,24 @@ { "name": "limit", "in": "query", - "description": "Maximum number of namespaces to return. Defaults to 100. Allowed range: 1-1000.", + "description": "Maximum number of namespaces to return. Defaults to 100. Allowed range: 1-200.", "schema": { "type": "integer", "default": 100, - "maximum": 1000, + "maximum": 200, "minimum": 1, - "description": "Maximum number of namespaces to return. Defaults to 100. Allowed range: 1-1000.", + "description": "Maximum number of namespaces to return. Defaults to 100. Allowed range: 1-200.", "format": "int32" } }, { - "name": "pageToken", + "name": "cursor", "in": "query", "description": "Opaque token from a previous response for the next page.", "schema": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token from a previous response for the next page." } } @@ -2711,13 +2734,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true } @@ -2849,7 +2872,7 @@ ] } }, - "/v1/stores/{storeId}/namespaces/{namespaceId}": { + "/iris/data/v1/agent-memory/stores/{storeId}/namespaces/{namespaceId}": { "delete": { "description": "Deletes an empty leaf namespace. Returns 409 when the namespace has children or memory placements, or when it changed concurrently.", "operationId": "DeleteNamespace", @@ -2857,26 +2880,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "namespaceId", "in": "path", - "description": "Server-generated namespace identifier.", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "required": true } @@ -3007,26 +3030,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "namespaceId", "in": "path", - "description": "Server-generated namespace identifier.", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "required": true } @@ -3163,26 +3186,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "namespaceId", "in": "path", - "description": "Server-generated namespace identifier.", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "required": true } @@ -3314,77 +3337,95 @@ ] } }, - "/v1/stores/{storeId}/session-memory": { + "/iris/data/v1/agent-memory/stores/{storeId}/sessions": { "get": { - "description": "Returns a paginated list of session IDs for a store.", + "description": "Returns paginated session rows with metadata and caller-selected order.", "operationId": "ListSessions", "parameters": [ { "name": "storeId", "in": "path", - "description": "The store instance ID.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "The store instance ID." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "limit", "in": "query", - "description": "Maximum number of sessions to return. Defaults to 100. Allowed range: 1-1000.", + "description": "Maximum number of sessions to return. Defaults to 100. Allowed range: 1-200.", "schema": { "type": "integer", "default": 100, - "maximum": 1000, + "maximum": 200, "minimum": 1, - "description": "Maximum number of sessions to return. Defaults to 100. Allowed range: 1-1000.", + "description": "Maximum number of sessions to return. Defaults to 100. Allowed range: 1-200.", "format": "int32" } }, { - "name": "pageToken", + "name": "cursor", "in": "query", - "description": "Opaque token from a previous response for the next page.", + "description": "Opaque token from a previous response for the next page. Bound to the effective filters and sort.", "schema": { "type": "string", - "description": "Opaque token from a previous response for the next page." + "maxLength": 1024, + "minLength": 1, + "description": "Opaque token from a previous response for the next page. Bound to the effective filters and sort." } }, { - "name": "filterOwnerId", + "name": "ownerId", "in": "query", - "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Mutually exclusive with includeAll.", + "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Combined with namespaceId using AND. Mutually exclusive with includeAll.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Mutually exclusive with includeAll." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Combined with namespaceId using AND. Mutually exclusive with includeAll." } }, { - "name": "namespaceRef", + "name": "namespaceId", "in": "query", - "description": "Filter sessions by stable namespace ID. Matching is exact and case-sensitive, excludes deprecated namespace labels and sessions without a namespace resource, and does not include descendants. Combined with filterOwnerId using AND. Mutually exclusive with includeAll.", + "description": "Filter by stable namespace ID. Combined with ownerId using AND. Mutually exclusive with includeAll.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Filter sessions by stable namespace ID. Matching is exact and case-sensitive, excludes deprecated namespace labels and sessions without a namespace resource, and does not include descendants. Combined with filterOwnerId using AND. Mutually exclusive with includeAll." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Filter by stable namespace ID. Combined with ownerId using AND. Mutually exclusive with includeAll." } }, { "name": "includeAll", "in": "query", - "description": "Set to true to list all sessions. Required when no filter is given; mutually exclusive with filters.", + "description": "Set to true to list all visible sessions. Required when no filter is given; mutually exclusive with filters.", "schema": { "type": "boolean", - "description": "Set to true to list all sessions. Required when no filter is given; mutually exclusive with filters." + "description": "Set to true to list all visible sessions. Required when no filter is given; mutually exclusive with filters." + } + }, + { + "name": "sortBy", + "in": "query", + "description": "Sort field. Defaults to updatedAt.", + "schema": { + "$ref": "#/components/schemas/SessionListSortBy" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "Sort direction. Defaults to desc for timestamps and asc for sessionId.", + "schema": { + "$ref": "#/components/schemas/SessionListSortOrder" } } ], @@ -3503,17 +3544,15 @@ "tags": [ "Session Memory" ] - } - }, - "/v1/stores/{storeId}/session-memory/events": { + }, "post": { - "description": "Appends a single event to a session. Creates the session if it does not exist. If sessionId is omitted, the server generates one.", - "operationId": "AddSessionEvent", + "description": "Creates a session with its first event. If sessionId is omitted, the server generates one. A sessionId that already exists is refused with 409 and the session is left unchanged; use AddSessionEvent to append to an existing session.", + "operationId": "CreateSession", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AddSessionEventRequestContent" + "$ref": "#/components/schemas/CreateSessionRequestContent" } } }, @@ -3526,9 +3565,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -3536,11 +3575,11 @@ ], "responses": { "201": { - "description": "AddSessionEvent 201 response", + "description": "CreateSession 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AddSessionEventResponseContent" + "$ref": "#/components/schemas/CreateSessionResponseContent" } } } @@ -3595,6 +3634,16 @@ } } }, + "409": { + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, "413": { "description": "PayloadTooLargeError 413 response", "content": { @@ -3671,7 +3720,7 @@ ] } }, - "/v1/stores/{storeId}/session-memory/{sessionId}": { + "/iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}": { "delete": { "description": "Deletes the session memory for a session.", "operationId": "DeleteSessionMemory", @@ -3682,9 +3731,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -3697,7 +3746,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The session ID." }, "required": true @@ -3822,9 +3871,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -3837,7 +3886,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The session ID." }, "required": true @@ -3969,10 +4018,20 @@ ] } }, - "/v1/stores/{storeId}/session-memory/{sessionId}/events/{eventId}": { - "delete": { - "description": "Deletes a single event from a session by event ID.", - "operationId": "DeleteSessionEvent", + "/iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}/events": { + "post": { + "description": "Appends a single event to a session. Creates the session if it does not exist.", + "operationId": "AddSessionEvent", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddSessionEventRequestContent" + } + } + }, + "required": true + }, "parameters": [ { "name": "storeId", @@ -3980,9 +4039,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -3995,28 +4054,22 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The session ID." }, "required": true - }, - { - "name": "eventId", - "in": "path", - "description": "The event ID.", - "schema": { - "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "The event ID." - }, - "required": true } ], "responses": { - "204": { - "description": "DeleteSessionEvent 204 response" + "201": { + "description": "AddSessionEvent 201 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddSessionEventResponseContent" + } + } + } }, "400": { "description": "BadRequestError 400 response", @@ -4078,6 +4131,16 @@ } } }, + "422": { + "description": "IngestionHookStoppedError 422 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IngestionHookStoppedErrorResponseContent" + } + } + } + }, "423": { "description": "ResourceSuspendedError 423 response", "content": { @@ -4117,15 +4180,27 @@ } } } + }, + "503": { + "description": "IngestionHookRetryError 503 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IngestionHookRetryErrorResponseContent" + } + } + } } }, "tags": [ "Session Memory" ] - }, - "get": { - "description": "Returns a single event from a session by event ID.", - "operationId": "GetSessionEvent", + } + }, + "/iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}/events/{eventId}": { + "delete": { + "description": "Deletes a single event from a session by event ID.", + "operationId": "DeleteSessionEvent", "parameters": [ { "name": "storeId", @@ -4133,9 +4208,9 @@ "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", "description": "The store instance ID." }, "required": true @@ -4148,7 +4223,7 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The session ID." }, "required": true @@ -4159,24 +4234,17 @@ "description": "The event ID.", "schema": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", "description": "The event ID." }, "required": true } ], "responses": { - "200": { - "description": "GetSessionEvent 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GetSessionEventResponseContent" - } - } - } + "204": { + "description": "DeleteSessionEvent 204 response" }, "400": { "description": "BadRequestError 400 response", @@ -4282,105 +4350,58 @@ "tags": [ "Session Memory" ] - } - }, - "/v1/stores/{storeId}/sessions": { + }, "get": { - "description": "Returns paginated session rows with metadata and caller-selected order. The ID-only ListSessions operation remains unchanged.", - "operationId": "ListSessionSummaries", + "description": "Returns a single event from a session by event ID.", + "operationId": "GetSessionEvent", "parameters": [ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "The store instance ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "The store instance ID." }, "required": true }, { - "name": "limit", - "in": "query", - "description": "Maximum number of sessions to return. Defaults to 100. Allowed range: 1-1000.", - "schema": { - "type": "integer", - "default": 100, - "maximum": 1000, - "minimum": 1, - "description": "Maximum number of sessions to return. Defaults to 100. Allowed range: 1-1000.", - "format": "int32" - } - }, - { - "name": "pageToken", - "in": "query", - "description": "Opaque token from a previous response for the next page. Bound to the effective filters and sort.", - "schema": { - "type": "string", - "description": "Opaque token from a previous response for the next page. Bound to the effective filters and sort." - } - }, - { - "name": "filterOwnerId", - "in": "query", - "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Combined with namespaceRef using AND. Mutually exclusive with includeAll.", + "name": "sessionId", + "in": "path", + "description": "The session ID.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Combined with namespaceRef using AND. Mutually exclusive with includeAll." - } + "pattern": "^[A-Za-z0-9_-]+$", + "description": "The session ID." + }, + "required": true }, { - "name": "namespaceRef", - "in": "query", - "description": "Filter by stable namespace ID. Combined with filterOwnerId using AND. Mutually exclusive with includeAll.", + "name": "eventId", + "in": "path", + "description": "The event ID.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Filter by stable namespace ID. Combined with filterOwnerId using AND. Mutually exclusive with includeAll." - } - }, - { - "name": "includeAll", - "in": "query", - "description": "Set to true to list all visible sessions. Required when no filter is given; mutually exclusive with filters.", - "schema": { - "type": "boolean", - "description": "Set to true to list all visible sessions. Required when no filter is given; mutually exclusive with filters." - } - }, - { - "name": "sortBy", - "in": "query", - "description": "Sort field. Defaults to updatedAt.", - "schema": { - "$ref": "#/components/schemas/SessionListSortBy" - } - }, - { - "name": "sortOrder", - "in": "query", - "description": "Sort direction. Defaults to desc for timestamps and asc for sessionId.", - "schema": { - "$ref": "#/components/schemas/SessionListSortOrder" - } + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", + "description": "The event ID." + }, + "required": true } ], "responses": { "200": { - "description": "ListSessionSummaries 200 response", + "description": "GetSessionEvent 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListSessionSummariesResponseContent" + "$ref": "#/components/schemas/GetSessionEventResponseContent" } } } @@ -4491,7 +4512,7 @@ ] } }, - "/v1/stores/{storeId}/sources/{sourceId}/memories": { + "/iris/data/v1/agent-memory/stores/{storeId}/sources/{sourceId}/memories": { "get": { "description": "Pages memories linked to one source. A source link does not grant access to a memory in another owner or namespace.", "operationId": "ListSourceMemories", @@ -4499,13 +4520,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, @@ -4525,13 +4546,13 @@ { "name": "ownerId", "in": "query", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants.", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." }, "required": true }, @@ -4546,10 +4567,14 @@ } }, { - "name": "pageToken", + "name": "cursor", "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } } ], @@ -4650,7 +4675,7 @@ ] } }, - "/v1/stores/{storeId}/summary-views": { + "/iris/data/v1/agent-memory/stores/{storeId}/summary-views": { "get": { "description": "Lists Summary View definitions and high-level state. Partition values are not included.", "operationId": "ListSummaryViews", @@ -4658,13 +4683,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, @@ -4680,10 +4705,14 @@ } }, { - "name": "pageToken", + "name": "cursor", "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } } ], @@ -4800,13 +4829,13 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true } @@ -4873,11 +4902,11 @@ } }, "409": { - "description": "SummaryViewConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SummaryViewConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" } } } @@ -4928,7 +4957,7 @@ ] } }, - "/v1/stores/{storeId}/summary-views/{viewId}": { + "/iris/data/v1/agent-memory/stores/{storeId}/summary-views/{viewId}": { "delete": { "description": "Marks a Summary View deleting and asynchronously removes its schedule and materializations in bounded batches. Repeated requests are idempotent.", "operationId": "DeleteSummaryView", @@ -4936,26 +4965,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "viewId", "in": "path", - "description": "Server-generated Summary View identifier.", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "required": true } @@ -5012,11 +5041,11 @@ } }, "409": { - "description": "SummaryViewConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SummaryViewConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" } } } @@ -5063,26 +5092,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "viewId", "in": "path", - "description": "Server-generated Summary View identifier.", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "required": true } @@ -5199,26 +5228,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "viewId", "in": "path", - "description": "Server-generated Summary View identifier.", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "required": true } @@ -5285,11 +5314,11 @@ } }, "409": { - "description": "SummaryViewConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SummaryViewConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" } } } @@ -5340,7 +5369,7 @@ ] } }, - "/v1/stores/{storeId}/summary-views/{viewId}/refresh": { + "/iris/data/v1/agent-memory/stores/{storeId}/summary-views/{viewId}/refresh": { "post": { "description": "Asynchronously enqueues one exact partition refresh or a complete view reconciliation. It never performs generation synchronously.", "operationId": "RefreshSummaryView", @@ -5358,26 +5387,26 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "viewId", "in": "path", - "description": "Server-generated Summary View identifier.", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "required": true } @@ -5444,11 +5473,11 @@ } }, "409": { - "description": "SummaryViewConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SummaryViewConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" } } } @@ -5489,7 +5518,7 @@ ] } }, - "/v1/stores/{storeId}/summary-views/{viewId}/result": { + "/iris/data/v1/agent-memory/stores/{storeId}/summary-views/{viewId}/result": { "get": { "description": "Returns one authorized exact Summary View partition after validating its contributing source records. Invalid output is withheld while repair is pending.", "operationId": "GetSummaryViewResult", @@ -5497,75 +5526,75 @@ { "name": "storeId", "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes.", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated store IDs are typically 32-character UUIDs without dashes." + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "viewId", "in": "path", - "description": "Server-generated Summary View identifier.", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "required": true }, { "name": "ownerId", "in": "query", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants.", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." } }, { "name": "sessionId", "in": "query", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes.", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." } }, { - "name": "namespaceRef", + "name": "namespaceId", "in": "query", - "description": "Server-generated namespace identifier.", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", "schema": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." } }, { "name": "memoryType", "in": "query", - "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, and `message`.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes.\n", + "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, `message`, and `session_summary`.\nThe legacy `session_summary_view` name remains reserved. Search filters for either\nsummary name match both, except on stores with an existing custom `session_summary`\ntype, where each name retains its separate meaning.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes.\n", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, and `message`.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes." + "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, `message`, and `session_summary`.\nThe legacy `session_summary_view` name remains reserved. Search filters for either\nsummary name match both, except on stores with an existing custom `session_summary`\ntype, where each name retains its separate meaning.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes." } }, { @@ -5638,11 +5667,11 @@ } }, "409": { - "description": "SummaryViewConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SummaryViewConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" } } } @@ -5688,6 +5717,7 @@ "schemas": { "AddSessionEventRequestContent": { "type": "object", + "description": "The event fields shared by CreateSession and AddSessionEvent.", "properties": { "idempotencyKey": { "type": "string", @@ -5696,30 +5726,19 @@ "pattern": "^[ -~]+$", "description": "Required when the store selects session.append input hooks. Reuse this key only for an identical request; accepted retries reuse the saved decision and event identity." }, - "sessionId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Optional session ID. If omitted, the server generates a unique ID." - }, "actorId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Unique actor identifier (1-255 chars). Can represent a user, agent, or any participant." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Optional deprecated namespace label for the session. This label does not create or resolve a namespace resource. Do not supply it with namespaceRef.\n\nLike `ownerId`, this is a session-level value taken from the first event: the value sent with the first event of a session is stored on the session, and values sent with later events are ignored. Omit it to leave extracted memories without a namespace.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRefInput" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Existing namespace for the session. Like ownerId, it is taken from the first event; later values are ignored. Omit it to leave the session and its extracted memories without a namespace." }, "role": { "$ref": "#/components/schemas/MessageRole" @@ -5896,12 +5915,12 @@ "type": { "$ref": "#/components/schemas/BadRequestErrorType" }, - "fields": { + "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" }, - "description": "Optional field-level validation errors." + "description": "Every invalid request member found, when the failure is about members." } }, "required": [ @@ -5914,7 +5933,12 @@ "type": "string", "description": "Problem type URI for bad request errors.", "enum": [ - "/errors/invalid-data" + "/errors/invalid-data", + "/errors/invalid-cursor", + "/errors/unknown-request-member", + "/errors/invalid-model-config", + "/errors/model-config-immutable", + "/errors/model-config-not-supported" ] }, "BulkCreateLongTermMemoriesRequestContent": { @@ -5952,8 +5976,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "description": "IDs of successfully created memory records. Always returned; empty when no records were created." }, @@ -5979,8 +6003,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "maxItems": 100, "minItems": 1, @@ -6001,8 +6025,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "description": "IDs of successfully deleted memory records. Always returned; empty when no records were deleted." }, @@ -6022,21 +6046,36 @@ "type": "object", "description": "Error detail for a single item in a bulk operation.", "properties": { - "id": { + "memoryId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Memory record ID of the item that failed." }, - "error": { + "type": { + "type": "string", + "description": "Problem type URI from the error registry, as on a whole-request error (RFC 9457)." + }, + "title": { + "type": "string", + "description": "Short, human-readable summary of the problem type." + }, + "status": { + "type": "integer", + "description": "The HTTP status the item would have answered on its own.", + "format": "int32" + }, + "detail": { "type": "string", - "description": "Error message describing the failure." + "description": "Human-readable explanation of this item's failure." } }, "required": [ - "error", - "id" + "memoryId", + "status", + "title", + "type" ] }, "ConflictErrorResponseContent": { @@ -6063,6 +6102,10 @@ }, "type": { "$ref": "#/components/schemas/ConflictErrorType" + }, + "existingId": { + "type": "string", + "description": "The ID of the existing resource the request collided with, when the conflict names one." } }, "required": [ @@ -6075,7 +6118,25 @@ "type": "string", "description": "Problem type URI for conflict errors.", "enum": [ - "/errors/conflict" + "/errors/conflict", + "/errors/entry-not-published", + "/errors/entry-key-conflict", + "/errors/content-limit-exceeded", + "/errors/pinned-entry-unavailable", + "/errors/proposal-already-exists", + "/errors/proposal-evidence-conflict", + "/errors/proposal-evidence-capacity", + "/errors/proposal-trashed", + "/errors/proposal-open", + "/errors/proposal-promotion-locked", + "/errors/extraction-disabled", + "/errors/gateway-mutation-in-progress", + "/errors/surface-mutation-in-progress", + "/errors/namespace-conflict", + "/errors/gateway-not-empty", + "/errors/gateway-deleting", + "/errors/catalog-publication-conflict", + "/errors/summary-view-conflict" ] }, "Content": { @@ -6122,15 +6183,15 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." }, "extractorId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Extractor identifier (1-64 chars, alphanumeric and dashes)." + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters." }, "idempotencyKey": { "type": "string", @@ -6154,10 +6215,10 @@ "properties": { "ingestionId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated document ingestion identifier." + "maxLength": 36, + "minLength": 36, + "pattern": "^ing_[0-9a-f]{32}$", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters." }, "status": { "$ref": "#/components/schemas/DocumentIngestionStatus" @@ -6172,12 +6233,12 @@ "type": "object", "description": "A memory record to create.", "properties": { - "id": { + "memoryId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Client-provided memory record ID for idempotent creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Client-provided memory record ID. It must not already exist; change an existing memory with UpdateLongTermMemory." }, "text": { "type": "string", @@ -6196,26 +6257,22 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Session ID associated with this memory (1-64 chars, alphanumeric and dashes)." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Owner ID associated with this memory (1-64 chars, alphanumeric and dashes)." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Owner ID associated with this memory." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Optional deprecated namespace label. It does not create or resolve a namespace resource. Do not supply it with namespaceRef. If both fields are omitted, the record is created without a namespace. Automatic routing does not place an un-namespaced record in a shared namespace.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRefInput" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Existing namespace resource for the memory. The destination must pass admission and is never rerouted. If it is omitted, the record is created without a namespace. Automatic routing does not place an un-namespaced record in a shared namespace." }, "topics": { "type": "array", @@ -6233,7 +6290,7 @@ } }, "required": [ - "id", + "memoryId", "ownerId", "text" ] @@ -6259,16 +6316,16 @@ }, "parentId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", "description": "Parent namespace for a direct child." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Owner for a personal root or path. Required for personal scope; omit for shared roots and children." } } @@ -6284,6 +6341,76 @@ "namespace" ] }, + "CreateSessionRequestContent": { + "type": "object", + "description": "The event fields shared by CreateSession and AddSessionEvent.", + "properties": { + "idempotencyKey": { + "type": "string", + "maxLength": 128, + "minLength": 1, + "pattern": "^[ -~]+$", + "description": "Required when the store selects session.append input hooks. Reuse this key only for an identical request; accepted retries reuse the saved decision and event identity." + }, + "actorId": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Unique actor identifier (1-255 chars). Can represent a user, agent, or any participant." + }, + "namespaceId": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Existing namespace for the session. Like ownerId, it is taken from the first event; later values are ignored. Omit it to leave the session and its extracted memories without a namespace." + }, + "role": { + "$ref": "#/components/schemas/MessageRole" + }, + "content": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Content" + }, + "description": "The message content as an array of typed content parts." + }, + "createdAt": { + "type": "string", + "description": "Client-supplied timestamp for when the event happened (UTC).", + "format": "date-time" + }, + "metadata": { + "description": "Optional metadata as any valid JSON value." + }, + "sessionId": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Optional session ID. If omitted, the server generates a unique ID." + } + }, + "required": [ + "actorId", + "content", + "createdAt", + "role" + ] + }, + "CreateSessionResponseContent": { + "type": "object", + "description": "Response returned after appending a session event.", + "properties": { + "event": { + "$ref": "#/components/schemas/SessionEvent" + } + }, + "required": [ + "event" + ] + }, "CreateSummaryViewRequestContent": { "type": "object", "properties": { @@ -6292,14 +6419,15 @@ }, "name": { "type": "string", - "maxLength": 100, + "maxLength": 128, "minLength": 1, - "description": "Customer-visible Summary View name (1-100 characters)." + "description": "Display name of any API resource." }, "description": { "type": "string", - "maxLength": 200, - "description": "Optional Summary View description (up to 200 characters)." + "maxLength": 1024, + "minLength": 0, + "description": "Free-text description of any API resource. May be empty." }, "source": { "$ref": "#/components/schemas/SummaryViewSource" @@ -6307,9 +6435,6 @@ "filter": { "$ref": "#/components/schemas/LongTermMemoryFilter" }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" - }, "groupBy": { "type": "array", "items": { @@ -6342,35 +6467,33 @@ }, "CreateSummaryViewResponseContent": { "type": "object", - "description": "An owned Summary View definition. Results are separate derived state and never enter long-term-memory search.", + "description": "A Summary View definition. Results are separate derived state and never enter long-term-memory search.", "properties": { - "id": { + "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "ownerId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Immutable canonical user ID assigned by the server. Clients cannot set ownership." + "description": "Immutable canonical user ID assigned by the server. Empty when ownership enforcement is disabled and the caller has no canonical user ID. Clients cannot set ownership." }, "visibility": { "$ref": "#/components/schemas/SummaryViewVisibility" }, "name": { "type": "string", - "maxLength": 100, + "maxLength": 128, "minLength": 1, - "description": "Customer-visible Summary View name (1-100 characters)." + "description": "Display name of any API resource." }, "description": { "type": "string", - "maxLength": 200, - "description": "Optional Summary View description (up to 200 characters)." + "maxLength": 1024, + "minLength": 0, + "description": "Free-text description of any API resource. May be empty." }, "source": { "$ref": "#/components/schemas/SummaryViewSource" @@ -6378,9 +6501,6 @@ "filter": { "$ref": "#/components/schemas/LongTermMemoryFilter" }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" - }, "groupBy": { "type": "array", "items": { @@ -6422,9 +6542,7 @@ "required": [ "createdAt", "definitionVersion", - "filterOp", "groupBy", - "id", "name", "output", "ownerId", @@ -6432,6 +6550,7 @@ "source", "state", "updatedAt", + "viewId", "visibility" ] }, @@ -6471,10 +6590,10 @@ "properties": { "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "state": { "$ref": "#/components/schemas/SummaryViewState" @@ -6488,19 +6607,19 @@ "DocumentIngestionCleanupState": { "type": "string", "enum": [ - "pending", - "deleted", - "failed" + "PENDING", + "DELETED", + "FAILED" ] }, "DocumentIngestionProcessingState": { "type": "string", "enum": [ - "queued", - "running", - "succeeded", - "failed", - "partial" + "QUEUED", + "RUNNING", + "SUCCEEDED", + "FAILED", + "PARTIAL" ] }, "DocumentIngestionRecord": { @@ -6508,10 +6627,10 @@ "properties": { "ingestionId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated document ingestion identifier." + "maxLength": 36, + "minLength": 36, + "pattern": "^ing_[0-9a-f]{32}$", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters." }, "status": { "$ref": "#/components/schemas/DocumentIngestionStatus" @@ -6533,14 +6652,16 @@ }, "extractorId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Extractor identifier (1-64 chars, alphanumeric and dashes)." + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters." }, "extractorRevision": { - "type": "integer", - "format": "int64" + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "completedChunks": { "type": "integer", @@ -6653,38 +6774,38 @@ "description": "Problem type URI for failed-dependency errors.", "enum": [ "/errors/resource-unavailable", - "/errors/database-out-of-memory" + "/errors/database-out-of-memory", + "/errors/invalid-model-credentials", + "/errors/model-quota-exceeded" ] }, "FieldError": { "type": "object", - "description": "Validation error details for a single request field.", + "description": "One invalid request member. A body member is named by `pointer`, a path or query parameter by `parameter`; exactly one of the two is present.", "properties": { - "field": { + "pointer": { "type": "string", - "description": "Name of the invalid request field." + "description": "JSON Pointer (RFC 6901) to the invalid body member, such as `/vectorSpace/dimensions`." }, - "rule": { + "parameter": { "type": "string", - "description": "Validation rule that was violated." + "description": "Name of the invalid path or query parameter, such as `limit`." }, - "message": { + "detail": { "type": "string", - "description": "Human-readable validation error message." + "description": "What is wrong with the member, in fixed words about the rule it broke, never the rejected value." } }, "required": [ - "field", - "message", - "rule" + "detail" ] }, "FilterConjunction": { "type": "string", "description": "Filter conjunction mode.", "enum": [ - "all", - "any" + "ALL", + "ANY" ] }, "ForbiddenErrorResponseContent": { @@ -6752,11 +6873,11 @@ "type": "object", "description": "A long-term memory record.", "properties": { - "id": { + "memoryId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Unique memory record ID." }, "text": { @@ -6774,26 +6895,22 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Session ID associated with this memory." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Owner ID associated with this memory." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Deprecated namespace label. Absent when the record uses namespaceRef or has no namespace.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRef" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Current namespace. Absent when the record has no namespace." }, "topics": { "type": "array", @@ -6826,8 +6943,10 @@ }, "description": "Generic source links for this memory. Document sources include the customer document ID and revision that produced the memory." }, - "sourcesNextPageToken": { + "sourcesNextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token for additional source links when this response truncated attribution. Absent when every link is included." }, "documentManaged": { @@ -6837,7 +6956,7 @@ }, "required": [ "createdAt", - "id", + "memoryId", "text", "updatedAt" ] @@ -6884,26 +7003,22 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "The session ID." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "The owner of the session, set from the actorId of the first event." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Deprecated namespace label for the session, set from the first event. Absent when the session uses namespaceRef or has no namespace.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRef" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Current namespace for the session, set from the first event. Absent when the session has no namespace." }, "events": { "type": "array", @@ -6924,35 +7039,33 @@ }, "GetSummaryViewResponseContent": { "type": "object", - "description": "An owned Summary View definition. Results are separate derived state and never enter long-term-memory search.", + "description": "A Summary View definition. Results are separate derived state and never enter long-term-memory search.", "properties": { - "id": { + "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "ownerId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Immutable canonical user ID assigned by the server. Clients cannot set ownership." + "description": "Immutable canonical user ID assigned by the server. Empty when ownership enforcement is disabled and the caller has no canonical user ID. Clients cannot set ownership." }, "visibility": { "$ref": "#/components/schemas/SummaryViewVisibility" }, "name": { "type": "string", - "maxLength": 100, + "maxLength": 128, "minLength": 1, - "description": "Customer-visible Summary View name (1-100 characters)." + "description": "Display name of any API resource." }, "description": { "type": "string", - "maxLength": 200, - "description": "Optional Summary View description (up to 200 characters)." + "maxLength": 1024, + "minLength": 0, + "description": "Free-text description of any API resource. May be empty." }, "source": { "$ref": "#/components/schemas/SummaryViewSource" @@ -6960,9 +7073,6 @@ "filter": { "$ref": "#/components/schemas/LongTermMemoryFilter" }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" - }, "groupBy": { "type": "array", "items": { @@ -7004,9 +7114,7 @@ "required": [ "createdAt", "definitionVersion", - "filterOp", "groupBy", - "id", "name", "output", "ownerId", @@ -7014,6 +7122,7 @@ "source", "state", "updatedAt", + "viewId", "visibility" ] }, @@ -7022,10 +7131,10 @@ "properties": { "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "scope": { "$ref": "#/components/schemas/SummaryViewScope" @@ -7072,8 +7181,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "description": "The memory IDs selected for the materialized value. Included only when requested with includeSourceMemoryIds=true." }, @@ -7180,8 +7289,10 @@ "$ref": "#/components/schemas/HookStatusSource" }, "configRevision": { - "type": "integer", - "format": "int64" + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "state": { "type": "string" @@ -7289,46 +7400,55 @@ "IngestionHookStoppedState": { "type": "string", "enum": [ - "rejected", - "failed", - "expired", - "cancelled", - "conflict" + "REJECTED", + "FAILED", + "EXPIRED", + "CANCELLED", + "CONFLICT" ] }, "ListDocumentIngestionOutputsResponseContent": { "type": "object", "properties": { - "memoryIds": { + "items": { "type": "array", "items": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." } + }, + "nextCursor": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ - "memoryIds" + "items" ] }, "ListIngestionHookStatusesResponseContent": { "type": "object", "properties": { - "statuses": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionHookStatus" } }, "nextCursor": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ - "statuses" + "items" ] }, "ListMemorySourceEvidenceResponseContent": { @@ -7351,8 +7471,11 @@ "$ref": "#/components/schemas/MemorySourceLink" } }, - "nextPageToken": { - "type": "string" + "nextCursor": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ @@ -7368,8 +7491,10 @@ "$ref": "#/components/schemas/Namespace" } }, - "nextPageToken": { + "nextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token for fetching the next page. Omitted when no more results." } }, @@ -7377,7 +7502,7 @@ "items" ] }, - "ListSessionSummariesResponseContent": { + "ListSessionsResponseContent": { "type": "object", "description": "Paginated session rows for a store.", "properties": { @@ -7387,47 +7512,15 @@ "$ref": "#/components/schemas/SessionListItem" } }, - "total": { - "type": "integer", - "format": "int32" - }, - "nextPageToken": { - "type": "string" - } - }, - "required": [ - "items", - "total" - ] - }, - "ListSessionsResponseContent": { - "type": "object", - "description": "Paginated list of session IDs for a store.", - "properties": { - "items": { - "type": "array", - "items": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." - }, - "description": "List of session IDs. Always returned; empty when the store has no sessions." - }, - "total": { - "type": "integer", - "description": "Total number of matching sessions.", - "format": "int32" - }, - "nextPageToken": { + "nextCursor": { "type": "string", - "description": "Opaque token for fetching the next page. Omitted when no more results." + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ - "items", - "total" + "items" ] }, "ListSourceMemoriesResponseContent": { @@ -7439,8 +7532,11 @@ "$ref": "#/components/schemas/MemoryRecord" } }, - "nextPageToken": { - "type": "string" + "nextCursor": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ @@ -7456,8 +7552,11 @@ "$ref": "#/components/schemas/SummaryView" } }, - "nextPageToken": { - "type": "string" + "nextCursor": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ @@ -7482,21 +7581,21 @@ "type": "object", "description": "Grouping of filter conditions for long-term memory search.", "properties": { + "op": { + "$ref": "#/components/schemas/FilterConjunction" + }, "sessionId": { "$ref": "#/components/schemas/SessionIdFilter" }, "ownerId": { "$ref": "#/components/schemas/OwnerIdFilter" }, - "namespace": { - "$ref": "#/components/schemas/NamespaceFilter" - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRefFilter" + "namespaceId": { + "$ref": "#/components/schemas/NamespaceIdFilter" }, "unnamespaced": { "type": "boolean", - "description": "When true, matches only records that have neither a deprecated namespace label nor a namespace resource placement. This scope is always combined with every other filter condition. Do not supply namespace or namespaceRef with this field." + "description": "When true, matches only records that have no namespace. This scope is always combined with every other filter condition. Do not supply namespaceId with this field." }, "topics": { "$ref": "#/components/schemas/TopicsFilter" @@ -7524,20 +7623,20 @@ "type": "string", "description": "Direction used to order long-term memory search results.", "enum": [ - "asc", - "desc" + "ASC", + "DESC" ] }, "MatcherKind": { "type": "string", "description": "The matching techniques this API supports.", "enum": [ - "regex" + "REGEX" ] }, "MatcherSpec": { "type": "object", - "description": "How a detector matches, as a tagged union of techniques.\n\nExactly the block naming the declared kind must be present; a block belonging to\nany other kind is rejected rather than guessed at. Further kinds are additive.", + "description": "How a detector matches, as a tagged union of techniques.\n\nExactly the block naming the declared kind must be present; a block belonging to\nany other kind is rejected rather than guessed at. New kinds may be added.", "properties": { "kind": { "$ref": "#/components/schemas/MatcherKind" @@ -7550,57 +7649,15 @@ "kind" ] }, - "MemoryFailedDependencyErrorResponseContent": { - "type": "object", - "description": "A resource or model-provider dependency required by Agent Memory could not complete the request.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 424, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/MemoryFailedDependencyErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "MemoryFailedDependencyErrorType": { - "type": "string", - "description": "Problem type URI for Agent Memory failed-dependency errors.", - "enum": [ - "/errors/resource-unavailable", - "/errors/database-out-of-memory", - "/errors/invalid-model-credentials", - "/errors/model-quota-exceeded" - ] - }, "MemoryRecord": { "type": "object", "description": "A long-term memory record.", "properties": { - "id": { + "memoryId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Unique memory record ID." }, "text": { @@ -7618,26 +7675,22 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Session ID associated with this memory." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Owner ID associated with this memory." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Deprecated namespace label. Absent when the record uses namespaceRef or has no namespace.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRef" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Current namespace. Absent when the record has no namespace." }, "topics": { "type": "array", @@ -7670,8 +7723,10 @@ }, "description": "Generic source links for this memory. Document sources include the customer document ID and revision that produced the memory." }, - "sourcesNextPageToken": { + "sourcesNextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token for additional source links when this response truncated attribution. Absent when every link is included." }, "documentManaged": { @@ -7681,7 +7736,7 @@ }, "required": [ "createdAt", - "id", + "memoryId", "text", "updatedAt" ] @@ -7702,7 +7757,7 @@ }, "capturedAt": { "type": "string", - "description": "UTC time when the producer prepared the input for extraction, before model invocation. Preserved through checkpoint replay. This is not the source event time.", + "description": "UTC time when the producer prepared the input for extraction, before model invocation. This is not the source event time.", "format": "date-time" }, "producer": { @@ -7710,10 +7765,10 @@ }, "ingestionId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated document ingestion identifier." + "maxLength": 36, + "minLength": 36, + "pattern": "^ing_[0-9a-f]{32}$", + "description": "Server-generated document ingestion identifier: ing_ followed by 32 lowercase hex characters." }, "chunkId": { "type": "string" @@ -7735,8 +7790,8 @@ "MemorySourceKind": { "type": "string", "enum": [ - "document", - "session" + "DOCUMENT", + "SESSION" ] }, "MemorySourceLink": { @@ -7766,9 +7821,11 @@ "$ref": "#/components/schemas/SessionSourceEvidence" } }, - "evidenceNextPageToken": { + "evidenceNextCursor": { "type": "string", - "description": "Opaque token for GET /v1/stores/{storeId}/long-term-memory/{memoryId}/sources/{sourceId}/evidence. Continues evidence or sessionEvidence for this source; absent when every item is included." + "maxLength": 1024, + "minLength": 1, + "description": "Opaque token for GET /iris/data/v1/agent-memory/stores/{storeId}/memories/{memoryId}/sources/{sourceId}/evidence. Continues evidence or sessionEvidence for this source; absent when every item is included." } }, "required": [ @@ -7822,14 +7879,18 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." }, "maxItems": 100, "minItems": 1 }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRefInput" + "namespaceId": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Existing namespace resource that receives the memories. Omit it to automatically route memories already in a shared namespace when automatic routing and the store's routing policy are enabled. Personal and un-namespaced memories keep their placement and receive a per-item error. If routing is disabled or no destination qualifies, the memory also keeps its placement and receives a per-item error." } }, "required": [ @@ -7845,8 +7906,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Memory record identifier (1-64 chars, alphanumeric and dashes). Client-provided for idempotent long-term memory creation." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." } }, "errors": { @@ -7864,8 +7925,8 @@ "type": "string", "description": "States a caller may set directly. Deleting is entered only by the delete operation.", "enum": [ - "active", - "disabled" + "ACTIVE", + "DISABLED" ] }, "Namespace": { @@ -7874,10 +7935,10 @@ "properties": { "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "name": { "type": "string", @@ -7888,22 +7949,24 @@ }, "parentId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "rootId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "ownerId": { "type": "string", + "maxLength": 64, "minLength": 1, - "description": "An opaque application-user ID selected by the platform for a namespace root." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "An application-user ID selected by the platform for a namespace root. It follows the same rules as ActorId." }, "scope": { "$ref": "#/components/schemas/NamespaceScope" @@ -7912,8 +7975,10 @@ "$ref": "#/components/schemas/NamespaceState" }, "revision": { - "type": "integer", - "format": "int64" + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "createdAt": { "type": "string", @@ -7942,123 +8007,30 @@ "updatedAt" ] }, - "NamespaceFilter": { - "type": "object", - "description": "Filter by namespace. Matching is case-insensitive.\n\nNamespace is optional, so records without one need care. The positive operators (`eq`, `in`, `all`) require the field to be present and therefore never match a record that has no namespace \u2014 including memories extracted from a session that has none. `ne` is a plain negation and *does* match those records, so use `eq` or `in` when you need strict namespace isolation rather than `ne` against the namespaces you want to exclude.\n\nOmit this filter to search across every namespace, and use it to keep recall inside one project, workspace, team, environment, or tenant.", - "properties": { - "eq": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Equals the given value.", - "deprecated": true - }, - "ne": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Not equal to the given value.", - "deprecated": true - }, - "in": { - "type": "array", - "items": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Deprecated flat namespace label for logical grouping. The value is 1-64 alphanumeric characters or dashes and has no hierarchy or scope semantics. Matching through `filter.namespace` is case-insensitive.\n\nThe field remains optional for backward compatibility. New integrations should use `namespaceRef` to reference an existing namespace resource.\n\nRecords produced by extraction inherit the namespace label stored on the session when the session was created.\n\nThis shape is deprecated: Use namespaceRef to reference a namespace resource.", - "deprecated": true - }, - "description": "Matches any of the given values." - }, - "all": { - "type": "array", - "items": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Deprecated flat namespace label for logical grouping. The value is 1-64 alphanumeric characters or dashes and has no hierarchy or scope semantics. Matching through `filter.namespace` is case-insensitive.\n\nThe field remains optional for backward compatibility. New integrations should use `namespaceRef` to reference an existing namespace resource.\n\nRecords produced by extraction inherit the namespace label stored on the session when the session was created.\n\nThis shape is deprecated: Use namespaceRef to reference a namespace resource.", - "deprecated": true - }, - "description": "Matches all of the given values." - } - } - }, - "NamespaceRef": { - "type": "object", - "description": "Reference to a namespace resource with its stable identifier and current display data.", - "properties": { - "namespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Stable namespace resource identifier." - }, - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9_-]+$", - "description": "Current namespace name." - }, - "path": { - "type": "string", - "maxLength": 1024, - "minLength": 1, - "description": "Current namespace path." - } - }, - "required": [ - "name", - "namespaceId", - "path" - ] - }, - "NamespaceRefFilter": { + "NamespaceIdFilter": { "type": "object", - "description": "Filter by stable namespace resource identifier. Supports exact or any-of matching and matches only resource-backed records, never deprecated namespace labels.", + "description": "Filter by stable namespace resource identifier. Supports exact or any-of matching.", "properties": { "eq": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", "description": "Equals the given value." }, "in": { "type": "array", "items": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "description": "Matches any of the given values." } } }, - "NamespaceRefInput": { - "type": "object", - "description": "Reference to an existing namespace resource for a write or namespace-scoped operation.", - "properties": { - "namespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Stable namespace resource identifier." - } - }, - "required": [ - "namespaceId" - ] - }, "NamespaceRoutingPolicy": { "type": "object", "description": "Store-level automatic namespace routing and admission policy. Global rules target shared namespaces only. Accept rules select candidates in list order. All enabled reject rules for a destination apply regardless of their position or how the destination was selected.", @@ -8087,10 +8059,14 @@ "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Routing rule identifier (1-64 chars). Published in logs, so it is an identifier rather than free text." + "description": "Routing rule identifier (1-64 chars)." }, - "destination": { - "$ref": "#/components/schemas/NamespaceRefInput" + "destinationNamespaceId": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "enabled": { "type": "boolean" @@ -8108,7 +8084,7 @@ }, "required": [ "action", - "destination", + "destinationNamespaceId", "enabled", "id" ] @@ -8133,8 +8109,8 @@ "NamespaceSortOrder": { "type": "string", "enum": [ - "asc", - "desc" + "ASC", + "DESC" ] }, "NamespaceState": { @@ -8188,7 +8164,9 @@ "type": "string", "description": "Problem type URI for not-found errors.", "enum": [ - "/errors/resource-not-found" + "/errors/resource-not-found", + "/errors/gateway-not-found", + "/errors/upstream-not-found" ] }, "OwnerIdFilter": { @@ -8199,14 +8177,14 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Equals the given value." }, "ne": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Not equal to the given value." }, "in": { @@ -8215,8 +8193,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." }, "description": "Matches any of the given values." }, @@ -8226,8 +8204,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." }, "description": "Matches all of the given values." } @@ -8313,10 +8291,10 @@ "properties": { "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "target": { "$ref": "#/components/schemas/SummaryViewRefreshTarget" @@ -8333,7 +8311,7 @@ }, "RegexSpec": { "type": "object", - "description": "A regular expression to match against.\n\nEvaluated by RE2, which runs in linear time \u2014 so an expensive pattern is not a\ndenial-of-service risk, but lookaround and backreferences are unavailable.\nRejected on write if it does not compile, or if it can match without consuming\ntext: such a pattern matches at every position, so it would exclude every memory\nthe store writes.", + "description": "A regular expression to match against.\n\nEvaluated by RE2, which runs in linear time — so an expensive pattern is not a\ndenial-of-service risk, but lookaround and backreferences are unavailable.\nRejected on write if it does not compile, or if it can match without consuming\ntext: such a pattern matches at every position, so it would exclude every memory\nthe store writes.", "properties": { "pattern": { "type": "string", @@ -8405,44 +8383,41 @@ }, "RouteStrategyKind": { "type": "string", - "description": "Routing strategy kinds. Unknown kinds are rejected. New kinds register on the evaluator without changing namespace records.", + "description": "Routing strategy kinds. Unknown kinds are rejected.", "enum": [ - "llm_prompt", - "matcher_spec" + "LLM_PROMPT", + "MATCHER_SPEC" ] }, "RoutingRuleAction": { "type": "string", "description": "Whether the rule accepts into the destination or rejects that destination.", "enum": [ - "accept", - "reject" + "ACCEPT", + "REJECT" ] }, "SearchLongTermMemoryRequestContent": { "type": "object", "description": "Semantic search request for long-term memory records.", "properties": { - "text": { + "query": { "type": "string", "description": "Text to use for semantic search." }, - "similarityThreshold": { + "minScore": { "type": "number", "maximum": 1, "minimum": 0, - "description": "The minimum similarity threshold for vector search results (normalized cosine similarity). Allowed range: 0-1.", - "format": "float" + "description": "The minimum score for vector search results: (2 - cosine distance) / 2. Allowed range: 0-1.", + "format": "double" }, "filter": { "$ref": "#/components/schemas/LongTermMemoryFilter" }, "excludeDocumentManaged": { "type": "boolean", - "description": "When true, omit document-managed memories from results. Automatic session reconciliation uses this; public search omits it so document memories remain visible." - }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" + "description": "When true, omit document-managed memories from results." }, "sortBy": { "$ref": "#/components/schemas/LongTermMemorySearchSortBy" @@ -8452,14 +8427,16 @@ }, "limit": { "type": "integer", - "default": 10, + "default": 50, "maximum": 100, "minimum": 1, - "description": "Maximum number of results to return. Defaults to 10. Allowed range: 1-100.", + "description": "Maximum number of results to return. Defaults to 50. Allowed range: 1-100.", "format": "int32" }, - "pageToken": { + "cursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token from a previous response for the next page." } } @@ -8475,8 +8452,10 @@ }, "description": "List of matching memory records. Always returned; empty when no records match." }, - "nextPageToken": { + "nextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token for fetching the next page. Omitted when no more results." } }, @@ -8490,23 +8469,23 @@ "properties": { "eventId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", "description": "Auto-generated event ID." }, "actorId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Unique actor identifier (1-255 chars). Can represent a user, agent, or any participant." }, "sessionId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Session identifier (client-provided or server-generated)." }, "role": { @@ -8551,14 +8530,14 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Equals the given value." }, "ne": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Not equal to the given value." }, "in": { @@ -8567,8 +8546,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." }, "description": "Matches any of the given values." }, @@ -8578,8 +8557,8 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." }, "description": "Matches all of the given values." } @@ -8593,14 +8572,14 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "The owner of the session, set from the actorId of the first event. Absent for a legacy session that has no recorded owner." }, "createdAt": { @@ -8611,8 +8590,12 @@ "type": "string", "format": "date-time" }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRef" + "namespaceId": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." } }, "required": [ @@ -8630,8 +8613,8 @@ "SessionListSortOrder": { "type": "string", "enum": [ - "asc", - "desc" + "ASC", + "DESC" ] }, "SessionSourceEvidence": { @@ -8650,7 +8633,7 @@ }, "capturedAt": { "type": "string", - "description": "UTC time when the producer prepared the input for extraction, before model invocation. Preserved through checkpoint replay. This is not the source event time.", + "description": "UTC time when the producer prepared the input for extraction, before model invocation. This is not the source event time.", "format": "date-time" }, "producer": { @@ -8660,10 +8643,10 @@ "type": "array", "items": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated event identifier (exactly 32 alphanumeric characters, UUID without dashes)." + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", + "description": "Server-generated event identifier: evt_ followed by 32 lowercase hex characters." }, "description": "Ordered IDs of events whose content was supplied to one model request. Input attribution, not fact citations." } @@ -8679,15 +8662,15 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." } }, "required": [ @@ -8705,9 +8688,9 @@ }, "summarizedUpToEventId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", "description": "Boundary event ID. This event and all events before it (by array position) are covered by the summary; `events` contains the retained turns after this boundary." }, "createdAt": { @@ -8759,7 +8742,7 @@ }, "StoreHealthResponseContent": { "type": "object", - "description": "Store-scoped RAM feature health.", + "description": "Store-scoped Agent Memory feature health.", "properties": { "status": { "$ref": "#/components/schemas/StoreHealthStatus" @@ -8777,42 +8760,40 @@ "type": "string", "description": "Store health status.", "enum": [ - "healthy", - "degraded", - "unavailable" + "HEALTHY", + "DEGRADED", + "UNAVAILABLE" ] }, "SummaryView": { "type": "object", - "description": "An owned Summary View definition. Results are separate derived state and never enter long-term-memory search.", + "description": "A Summary View definition. Results are separate derived state and never enter long-term-memory search.", "properties": { - "id": { + "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "ownerId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Immutable canonical user ID assigned by the server. Clients cannot set ownership." + "description": "Immutable canonical user ID assigned by the server. Empty when ownership enforcement is disabled and the caller has no canonical user ID. Clients cannot set ownership." }, "visibility": { "$ref": "#/components/schemas/SummaryViewVisibility" }, "name": { "type": "string", - "maxLength": 100, + "maxLength": 128, "minLength": 1, - "description": "Customer-visible Summary View name (1-100 characters)." + "description": "Display name of any API resource." }, "description": { "type": "string", - "maxLength": 200, - "description": "Optional Summary View description (up to 200 characters)." + "maxLength": 1024, + "minLength": 0, + "description": "Free-text description of any API resource. May be empty." }, "source": { "$ref": "#/components/schemas/SummaryViewSource" @@ -8820,9 +8801,6 @@ "filter": { "$ref": "#/components/schemas/LongTermMemoryFilter" }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" - }, "groupBy": { "type": "array", "items": { @@ -8864,9 +8842,7 @@ "required": [ "createdAt", "definitionVersion", - "filterOp", "groupBy", - "id", "name", "output", "ownerId", @@ -8874,48 +8850,10 @@ "source", "state", "updatedAt", + "viewId", "visibility" ] }, - "SummaryViewConflictErrorResponseContent": { - "type": "object", - "description": "A Summary View operation conflicts with the current definition or partition state.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 409, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/SummaryViewConflictErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "SummaryViewConflictErrorType": { - "type": "string", - "description": "Problem type URI for Summary View conflicts.", - "enum": [ - "/errors/summary-view-conflict" - ] - }, "SummaryViewEvictionPolicy": { "type": "object", "description": "Selects the bounded set of grouped results. Matching long-term-memory mutations make a scope recent.", @@ -8959,13 +8897,13 @@ "type": "string", "description": "Supported structured-output field types. This matches the custom-memory field vocabulary.", "enum": [ - "str", - "int", - "float", - "bool", - "list[str]", - "list[float]", - "object" + "STRING", + "INTEGER", + "FLOAT", + "BOOLEAN", + "STRING_LIST", + "FLOAT_LIST", + "OBJECT" ] }, "SummaryViewGroupField": { @@ -8974,7 +8912,7 @@ "enum": [ "ownerId", "sessionId", - "namespaceRef", + "namespaceId", "memoryType" ] }, @@ -9002,8 +8940,8 @@ "type": "string", "description": "Summary View output format.", "enum": [ - "text", - "structured" + "TEXT", + "STRUCTURED" ] }, "SummaryViewQuotaCode": { @@ -9019,7 +8957,7 @@ }, "SummaryViewQuotaErrorResponseContent": { "type": "object", - "description": "A Summary View operation exceeded an enabled store quota. Exact ceilings are deployment configuration established from benchmark evidence.", + "description": "A Summary View operation exceeded an enabled store quota. Exact limits depend on the deployment.", "properties": { "title": { "type": "string", @@ -9064,8 +9002,8 @@ "type": "string", "description": "Summary View refresh mode.", "enum": [ - "manual", - "continuous" + "MANUAL", + "CONTINUOUS" ] }, "SummaryViewRefreshPolicy": { @@ -9094,8 +9032,8 @@ "type": "string", "description": "Manual refresh target. Partition refreshes require an exact configured scope; full refreshes reconcile every current and prior partition.", "enum": [ - "partition", - "full" + "PARTITION", + "FULL" ] }, "SummaryViewResultErrorCode": { @@ -9113,12 +9051,12 @@ "type": "string", "description": "Materialization refresh state.", "enum": [ - "cold", - "pending", - "ready", - "empty", - "refreshing", - "failed" + "COLD", + "PENDING", + "READY", + "EMPTY", + "REFRESHING", + "FAILED" ] }, "SummaryViewResultValue": { @@ -9150,7 +9088,7 @@ }, "SummaryViewSchema": { "type": "object", - "description": "Bounded structured-output schema. Nested object schemas, required fields, and arbitrary JSON Schema are not supported in the MVP.", + "description": "Bounded structured-output schema. Nested object schemas, required fields, and arbitrary JSON Schema are not supported.", "properties": { "fields": { "type": "array", @@ -9173,46 +9111,46 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Actor/owner identifier (1-64 chars, alphanumeric and dashes). Used for users, agents, or other participants." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." }, "sessionId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Session identifier (1-64 chars, alphanumeric and dashes). When the server generates one, it uses a 32-character UUID without dashes." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." }, - "namespaceRef": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Server-generated namespace identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." }, "memoryType": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, and `message`.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes." + "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, `message`, and `session_summary`.\nThe legacy `session_summary_view` name remains reserved. Search filters for either\nsummary name match both, except on stores with an existing custom `session_summary`\ntype, where each name retains its separate meaning.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes." } } }, "SummaryViewSource": { "type": "string", - "description": "The source record family summarized by a Summary View. The MVP supports long-term memory only.", + "description": "The source record family summarized by a Summary View. Only long-term memory is supported.", "enum": [ - "long_term" + "LONG_TERM" ] }, "SummaryViewState": { "type": "string", "description": "Summary View definition lifecycle state.", "enum": [ - "active", - "disabled", - "deleting" + "ACTIVE", + "DISABLED", + "DELETING" ] }, "SummaryViewVisibility": { @@ -9365,7 +9303,8 @@ "type": "string", "description": "Problem type URI for unexpected internal errors.", "enum": [ - "/errors/unexpected-error" + "/errors/unexpected-error", + "/errors/content-integrity-failed" ] }, "UpdateLongTermMemoryFieldsRequestContent": { @@ -9379,16 +9318,12 @@ "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", "description": "The caller's bound memory type. The update is rejected unless the record's stored memoryType matches." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "The caller's current deprecated namespace label. The update is rejected with 409 unless the record still stores that label. Do not supply it with namespaceRef.\n\nOmit both namespace and namespaceRef to assert that the record has no namespace placement. Omission does not mean \"any namespace\".", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRefInput" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "The caller's current namespace. The update is rejected with 409 unless the record is still in it. Omit it to assert that the record has no namespace placement; omission does not mean \"any namespace\"." }, "text": { "type": "string", @@ -9432,17 +9367,19 @@ "maxItems": 50, "description": "Updated topics (max 50 topics, each 1-100 chars)." }, - "namespace": { + "namespaceId": { "type": "string", - "description": "Updated deprecated namespace label. When provided, it must be 1-64 alphanumeric characters or dashes. Send an empty string to clear it.\nDo not supply it with namespaceRef.\n\nThis shape is deprecated: Use namespaceRef to reference a namespace resource.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRefInput" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Updated namespace placement." }, "ownerId": { "type": "string", - "description": "Updated owner ID. When provided, must be 1-64 chars alphanumeric and dashes and non-empty; omit the field to leave unchanged. Clearing is not supported because ownerId is required." + "maxLength": 64, + "minLength": 1, + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Updated owner ID. When provided, must follow the ActorId rules; omit the field to leave unchanged. Clearing is not supported because ownerId is required." }, "sessionId": { "type": "string", @@ -9454,11 +9391,11 @@ "type": "object", "description": "A long-term memory record.", "properties": { - "id": { + "memoryId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Unique memory record ID." }, "text": { @@ -9476,26 +9413,22 @@ "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^[A-Za-z0-9_-]+$", "description": "Session ID associated with this memory." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", "description": "Owner ID associated with this memory." }, - "namespace": { + "namespaceId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Deprecated namespace label. Absent when the record uses namespaceRef or has no namespace.", - "deprecated": true - }, - "namespaceRef": { - "$ref": "#/components/schemas/NamespaceRef" + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Current namespace. Absent when the record has no namespace." }, "topics": { "type": "array", @@ -9528,8 +9461,10 @@ }, "description": "Generic source links for this memory. Document sources include the customer document ID and revision that produced the memory." }, - "sourcesNextPageToken": { + "sourcesNextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Opaque token for additional source links when this response truncated attribution. Absent when every link is included." }, "documentManaged": { @@ -9539,7 +9474,7 @@ }, "required": [ "createdAt", - "id", + "memoryId", "text", "updatedAt" ] @@ -9575,13 +9510,14 @@ "properties": { "name": { "type": "string", - "maxLength": 100, + "maxLength": 128, "minLength": 1, - "description": "Customer-visible Summary View name (1-100 characters)." + "description": "Display name of any API resource." }, "description": { "type": "string", - "maxLength": 200, + "maxLength": 1024, + "minLength": 0, "description": "New description. Send an empty string to clear it." }, "filter": { @@ -9591,9 +9527,6 @@ "type": "boolean", "description": "Clear the saved filter. Mutually exclusive with filter." }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" - }, "groupBy": { "type": "array", "items": { @@ -9626,35 +9559,33 @@ }, "UpdateSummaryViewResponseContent": { "type": "object", - "description": "An owned Summary View definition. Results are separate derived state and never enter long-term-memory search.", + "description": "A Summary View definition. Results are separate derived state and never enter long-term-memory search.", "properties": { - "id": { + "viewId": { "type": "string", - "maxLength": 32, - "minLength": 32, - "pattern": "^[a-zA-Z0-9]+$", - "description": "Server-generated Summary View identifier." + "maxLength": 35, + "minLength": 35, + "pattern": "^sv_[0-9a-f]{32}$", + "description": "Server-generated Summary View identifier: sv_ followed by 32 lowercase hex characters." }, "ownerId": { "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Immutable canonical user ID assigned by the server. Clients cannot set ownership." + "description": "Immutable canonical user ID assigned by the server. Empty when ownership enforcement is disabled and the caller has no canonical user ID. Clients cannot set ownership." }, "visibility": { "$ref": "#/components/schemas/SummaryViewVisibility" }, "name": { "type": "string", - "maxLength": 100, + "maxLength": 128, "minLength": 1, - "description": "Customer-visible Summary View name (1-100 characters)." + "description": "Display name of any API resource." }, "description": { "type": "string", - "maxLength": 200, - "description": "Optional Summary View description (up to 200 characters)." + "maxLength": 1024, + "minLength": 0, + "description": "Free-text description of any API resource. May be empty." }, "source": { "$ref": "#/components/schemas/SummaryViewSource" @@ -9662,9 +9593,6 @@ "filter": { "$ref": "#/components/schemas/LongTermMemoryFilter" }, - "filterOp": { - "$ref": "#/components/schemas/FilterConjunction" - }, "groupBy": { "type": "array", "items": { @@ -9706,9 +9634,7 @@ "required": [ "createdAt", "definitionVersion", - "filterOp", "groupBy", - "id", "name", "output", "ownerId", @@ -9716,9 +9642,22 @@ "source", "state", "updatedAt", + "viewId", "visibility" ] } + }, + "securitySchemes": { + "smithy.api.httpBearerAuth": { + "type": "http", + "description": "HTTP Bearer authentication", + "scheme": "Bearer" + } + } + }, + "security": [ + { + "smithy.api.httpBearerAuth": [] } - } + ] } diff --git a/content/develop/ai/context-engine/agent-playbooks/api-reference/openapi.json b/content/develop/ai/context-engine/agent-playbooks/api-reference/openapi.json index 048712b376..46f0eb2efc 100644 --- a/content/develop/ai/context-engine/agent-playbooks/api-reference/openapi.json +++ b/content/develop/ai/context-engine/agent-playbooks/api-reference/openapi.json @@ -1,19 +1,19 @@ { "openapi": "3.0.2", "info": { - "title": "Redis Agent Playbooks data-plane API", + "title": "PlaybookDataPlaneService", "version": "1.0.0", "description": "Public type-specific FAQ and Skill authoring, publication, and exact-version API." }, "paths": { - "/v1/playbooks/{playbookId}/skills": { + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/entries/discover": { "post": { - "operationId": "CreateSkill", + "operationId": "DiscoverEntries", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSkillRequestContent" + "$ref": "#/components/schemas/DiscoverEntriesRequestContent" } } }, @@ -33,22 +33,22 @@ } ], "responses": { - "201": { - "description": "CreateSkill 201 response", + "200": { + "description": "DiscoverEntries 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSkillResponseContent" + "$ref": "#/components/schemas/DiscoverEntriesResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -94,11 +94,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -144,33 +154,202 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/entries/lookup": { + "post": { + "description": "Resolves bounded entry references to compact management state. Results preserve input order and report misses explicitly. Each item is authoritative when read, but the batch is not a global snapshot.", + "operationId": "LookupEntries", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LookupEntriesRequestContent" + } + } + }, + "required": true }, - "tags": [ - "Skills" + "parameters": [ + { + "name": "playbookId", + "in": "path", + "description": "Opaque Playbook identifier.", + "schema": { + "type": "string", + "pattern": "^pb_[0-9a-f]{32}$", + "description": "Opaque Playbook identifier." + }, + "required": true + } ], - "summary": "Create a skill" - }, + "responses": { + "200": { + "description": "LookupEntries 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LookupEntriesResponseContent" + } + } + } + }, + "400": { + "description": "BadRequestError 400 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + } + }, + "401": { + "description": "AuthenticationError 401 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + } + }, + "403": { + "description": "ForbiddenError 403 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + } + }, + "404": { + "description": "NotFoundError 404 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + } + }, + "408": { + "description": "TimeoutError 408 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimeoutErrorResponseContent" + } + } + } + }, + "409": { + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + } + }, + "413": { + "description": "PayloadTooLargeError 413 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayloadTooLargeErrorResponseContent" + } + } + } + }, + "423": { + "description": "ResourceSuspendedError 423 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceSuspendedErrorResponseContent" + } + } + } + }, + "424": { + "description": "FailedDependencyError 424 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + } + }, + "429": { + "description": "TooManyRequestsError 429 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsErrorResponseContent" + } + } + } + }, + "500": { + "description": "UnexpectedError 500 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + } + }, + "503": { + "description": "ServiceUnavailableError 503 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + } + } + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs": { "get": { - "operationId": "ListSkills", + "operationId": "ListFaqs", "parameters": [ { "name": "playbookId", @@ -194,7 +373,7 @@ { "name": "sortOrder", "in": "query", - "description": "Defaults to desc. ID ties are always asc.", + "description": "Defaults to DESC. ID ties are always ASC.", "schema": { "$ref": "#/components/schemas/SortOrder" } @@ -219,51 +398,223 @@ "format": "date-time" } }, - { - "name": "published", - "in": "query", - "description": "Selects publication presence.", - "schema": { - "type": "boolean", - "description": "Selects publication presence." + { + "name": "published", + "in": "query", + "description": "Selects publication presence.", + "schema": { + "type": "boolean", + "description": "Selects publication presence." + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 50, + "maximum": 200, + "minimum": 1, + "format": "int32" + } + }, + { + "name": "cursor", + "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", + "schema": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." + } + } + ], + "responses": { + "200": { + "description": "ListFaqs 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListFaqsResponseContent" + } + } + } + }, + "400": { + "description": "BadRequestError 400 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + } + }, + "401": { + "description": "AuthenticationError 401 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + } + }, + "403": { + "description": "ForbiddenError 403 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + } + }, + "404": { + "description": "NotFoundError 404 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + } + }, + "408": { + "description": "TimeoutError 408 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimeoutErrorResponseContent" + } + } + } + }, + "409": { + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + } + }, + "413": { + "description": "PayloadTooLargeError 413 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayloadTooLargeErrorResponseContent" + } + } + } + }, + "423": { + "description": "ResourceSuspendedError 423 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceSuspendedErrorResponseContent" + } + } + } + }, + "424": { + "description": "FailedDependencyError 424 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + } + }, + "429": { + "description": "TooManyRequestsError 429 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsErrorResponseContent" + } + } + } + }, + "500": { + "description": "UnexpectedError 500 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + } + }, + "503": { + "description": "ServiceUnavailableError 503 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } } - }, - { - "name": "limit", - "in": "query", - "schema": { - "type": "integer", - "default": 50, - "maximum": 200, - "minimum": 1, - "format": "int32" + } + } + }, + "post": { + "operationId": "CreateFaq", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateFaqRequestContent" + } } }, + "required": true + }, + "parameters": [ { - "name": "cursor", - "in": "query", + "name": "playbookId", + "in": "path", + "description": "Opaque Playbook identifier.", "schema": { - "type": "string" - } + "type": "string", + "pattern": "^pb_[0-9a-f]{32}$", + "description": "Opaque Playbook identifier." + }, + "required": true } ], "responses": { - "200": { - "description": "ListSkills 200 response", + "201": { + "description": "CreateFaq 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListSkillsResponseContent" + "$ref": "#/components/schemas/CreateFaqResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -309,11 +660,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -359,39 +720,37 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "List skills" - }, - "delete": { - "description": "Deletes the requested Skill families sequentially. Each family deletion is atomic, but the batch is not: deletions completed before an error remain applied. Retrying the same request is safe because already absent entries are ignored.", - "operationId": "DeleteSkills", + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/bulk-delete": { + "post": { + "description": "Deletes the requested FAQ families sequentially. Each family deletion is atomic, but the batch is not: a family that cannot be deleted is reported in errors and the others are still processed, and deletions completed before a request-level error remain applied. Retrying the same request is safe because already absent entries are ignored.", + "operationId": "DeleteFaqs", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteSkillsRequestContent" + "$ref": "#/components/schemas/DeleteFaqsRequestContent" } } }, @@ -412,21 +771,21 @@ ], "responses": { "200": { - "description": "DeleteSkills 200 response", + "description": "DeleteFaqs 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteSkillsResponseContent" + "$ref": "#/components/schemas/DeleteFaqsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -472,11 +831,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -522,35 +891,41 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Delete multiple skills" + } } }, - "/v1/playbooks/{playbookId}/skills/{skillId}": { - "get": { - "operationId": "GetSkill", + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/search": { + "post": { + "operationId": "SearchFaqs", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchFaqsRequestContent" + } + } + }, + "required": true + }, "parameters": [ { "name": "playbookId", @@ -562,36 +937,25 @@ "description": "Opaque Playbook identifier." }, "required": true - }, - { - "name": "skillId", - "in": "path", - "description": "Opaque stable entry identifier.", - "schema": { - "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." - }, - "required": true } ], "responses": { "200": { - "description": "GetSkill 200 response", + "description": "SearchFaqs 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetSkillResponseContent" + "$ref": "#/components/schemas/SearchFaqsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -637,11 +1001,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -687,33 +1061,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Get a skill" - }, + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/{faqId}": { "delete": { - "operationId": "DeleteSkill", + "operationId": "DeleteFaq", "parameters": [ { "name": "playbookId", @@ -727,7 +1099,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -740,14 +1112,14 @@ ], "responses": { "204": { - "description": "DeleteSkill 204 response" + "description": "DeleteFaq 204 response" }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -793,11 +1165,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -843,45 +1225,29 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Delete a skill" - } - }, - "/v1/playbooks/{playbookId}/skills/{skillId}/versions": { - "post": { - "operationId": "AppendSkillVersion", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AppendSkillVersionRequestContent" - } - } - }, - "required": true - }, + } + }, + "get": { + "operationId": "GetFaq", "parameters": [ { "name": "playbookId", @@ -895,7 +1261,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -907,22 +1273,22 @@ } ], "responses": { - "201": { - "description": "AppendSkillVersion 201 response", + "200": { + "description": "GetFaq 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AppendSkillVersionResponseContent" + "$ref": "#/components/schemas/GetFaqResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -968,11 +1334,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -1018,33 +1394,32 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Append a skill version" - }, - "get": { - "operationId": "ListSkillVersions", + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/{faqId}/publication": { + "delete": { + "description": "Withdraws the FAQ publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", + "operationId": "WithdrawFaq", "parameters": [ { "name": "playbookId", @@ -1058,7 +1433,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -1067,63 +1442,25 @@ "description": "Opaque stable entry identifier." }, "required": true - }, - { - "name": "createdAfter", - "in": "query", - "description": "UTC timestamp resolved to microsecond precision.", - "schema": { - "type": "string", - "description": "UTC timestamp resolved to microsecond precision.", - "format": "date-time" - } - }, - { - "name": "createdBefore", - "in": "query", - "description": "UTC timestamp resolved to microsecond precision.", - "schema": { - "type": "string", - "description": "UTC timestamp resolved to microsecond precision.", - "format": "date-time" - } - }, - { - "name": "limit", - "in": "query", - "schema": { - "type": "integer", - "default": 50, - "maximum": 200, - "minimum": 1, - "format": "int32" - } - }, - { - "name": "cursor", - "in": "query", - "schema": { - "type": "string" - } } ], "responses": { "200": { - "description": "ListSkillVersions 200 response", + "description": "WithdrawFaq 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListSkillVersionsResponseContent" + "$ref": "#/components/schemas/WithdrawFaqResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -1169,11 +1506,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -1219,35 +1566,40 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } - } + } + } + }, + "put": { + "description": "Publishes the selected immutable FAQ version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", + "operationId": "PublishFaq", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublishFaqRequestContent" + } + } + }, + "required": true }, - "tags": [ - "Skills" - ], - "summary": "List skill versions" - } - }, - "/v1/playbooks/{playbookId}/skills/{skillId}/versions/{version}": { - "get": { - "operationId": "GetSkillVersion", "parameters": [ { "name": "playbookId", @@ -1261,7 +1613,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -1270,35 +1622,25 @@ "description": "Opaque stable entry identifier." }, "required": true - }, - { - "name": "version", - "in": "path", - "schema": { - "type": "integer", - "minimum": 1, - "format": "int32" - }, - "required": true } ], "responses": { "200": { - "description": "GetSkillVersion 200 response", + "description": "PublishFaq 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetSkillVersionResponseContent" + "$ref": "#/components/schemas/PublishFaqResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -1344,11 +1686,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -1394,46 +1746,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Get a skill version" + } } }, - "/v1/playbooks/{playbookId}/skills/{skillId}/publication": { - "put": { - "description": "Publishes the selected immutable Skill version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", - "operationId": "PublishSkill", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PublishSkillRequestContent" - } - } - }, - "required": true - }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/{faqId}/versions": { + "get": { + "operationId": "ListFaqVersions", "parameters": [ { "name": "playbookId", @@ -1447,7 +1784,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -1456,25 +1793,67 @@ "description": "Opaque stable entry identifier." }, "required": true + }, + { + "name": "createdAfter", + "in": "query", + "description": "UTC timestamp resolved to microsecond precision.", + "schema": { + "type": "string", + "description": "UTC timestamp resolved to microsecond precision.", + "format": "date-time" + } + }, + { + "name": "createdBefore", + "in": "query", + "description": "UTC timestamp resolved to microsecond precision.", + "schema": { + "type": "string", + "description": "UTC timestamp resolved to microsecond precision.", + "format": "date-time" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 50, + "maximum": 200, + "minimum": 1, + "format": "int32" + } + }, + { + "name": "cursor", + "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", + "schema": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." + } } ], "responses": { "200": { - "description": "PublishSkill 200 response", + "description": "ListFaqVersions 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PublishSkillResponseContent" + "$ref": "#/components/schemas/ListFaqVersionsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -1520,11 +1899,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -1570,34 +1959,39 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Publish a skill version" + } }, - "delete": { - "description": "Withdraws the Skill publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", - "operationId": "WithdrawSkill", + "post": { + "operationId": "AppendFaqVersion", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppendFaqVersionRequestContent" + } + } + }, + "required": true + }, "parameters": [ { "name": "playbookId", @@ -1611,7 +2005,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -1623,22 +2017,22 @@ } ], "responses": { - "200": { - "description": "WithdrawSkill 200 response", + "201": { + "description": "AppendFaqVersion 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WithdrawSkillResponseContent" + "$ref": "#/components/schemas/AppendFaqVersionResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -1684,11 +2078,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -1734,36 +2138,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Withdraw a skill" + } } }, - "/v1/playbooks/{playbookId}/skills/{skillId}/versions/{version}/resources/{resourceId}": { + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/{faqId}/versions/{version}": { "get": { - "description": "Returns the exact immutable Skill resource bytes. The Content-Digest response header carries their SHA-256 digest using RFC 9530 syntax.", - "operationId": "GetSkillResource", + "operationId": "GetFaqVersion", "parameters": [ { "name": "playbookId", @@ -1777,7 +2176,7 @@ "required": true }, { - "name": "skillId", + "name": "faqId", "in": "path", "description": "Opaque stable entry identifier.", "schema": { @@ -1796,53 +2195,25 @@ "format": "int32" }, "required": true - }, - { - "name": "resourceId", - "in": "path", - "description": "Opaque immutable Skill resource identifier.", - "schema": { - "type": "string", - "pattern": "^res_[0-9a-f]{24}$", - "description": "Opaque immutable Skill resource identifier." - }, - "required": true } ], "responses": { "200": { - "description": "GetSkillResource 200 response", - "headers": { - "Content-Digest": { - "description": "SHA-256 content digest using the RFC 9530 Content-Digest representation.", - "schema": { - "type": "string", - "pattern": "^sha-256=:[A-Za-z0-9+/]{43}=:$", - "description": "SHA-256 content digest using the RFC 9530 Content-Digest representation." - }, - "required": true - }, - "Content-Type": { - "schema": { - "type": "string" - }, - "required": true - } - }, + "description": "GetFaqVersion 200 response", "content": { - "*/*": { + "application/json": { "schema": { - "$ref": "#/components/schemas/GetSkillResourceOutputPayload" + "$ref": "#/components/schemas/GetFaqVersionResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -1888,11 +2259,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -1938,45 +2319,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Skills" - ], - "summary": "Read a skill resource" + } } }, - "/v1/playbooks/{playbookId}/faqs": { - "post": { - "operationId": "CreateFaq", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateFaqRequestContent" - } - } - }, - "required": true - }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/health": { + "get": { + "operationId": "GetPlaybookHealth", "parameters": [ { "name": "playbookId", @@ -1991,22 +2358,22 @@ } ], "responses": { - "201": { - "description": "CreateFaq 201 response", + "200": { + "description": "GetPlaybookHealth 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateFaqResponseContent" + "$ref": "#/components/schemas/GetPlaybookHealthResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -2052,11 +2419,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -2102,33 +2479,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Create an FAQ" - }, + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals": { "get": { - "operationId": "ListFaqs", + "operationId": "ListProposals", "parameters": [ { "name": "playbookId", @@ -2142,86 +2517,83 @@ "required": true }, { - "name": "sortBy", + "name": "view", "in": "query", - "description": "Default updatedAt descending, then entry ID ascending.", "schema": { - "$ref": "#/components/schemas/EntrySort" - } + "$ref": "#/components/schemas/ProposalView" + }, + "required": true }, { - "name": "sortOrder", + "name": "sortBy", "in": "query", - "description": "Defaults to desc. ID ties are always asc.", + "description": "Default updatedAt descending, then proposal ID ascending.", "schema": { - "$ref": "#/components/schemas/SortOrder" + "$ref": "#/components/schemas/ProposalSort" } }, { - "name": "createdAfter", + "name": "sortOrder", "in": "query", - "description": "Exclusive bound at microsecond precision.", + "description": "Defaults to ASC for deadlines, DESC otherwise. ID ties are always ASC.", "schema": { - "type": "string", - "description": "Exclusive bound at microsecond precision.", - "format": "date-time" + "$ref": "#/components/schemas/SortOrder" } }, { - "name": "createdBefore", + "name": "limit", "in": "query", - "description": "Exclusive bound at microsecond precision.", "schema": { - "type": "string", - "description": "Exclusive bound at microsecond precision.", - "format": "date-time" + "type": "integer", + "default": 50, + "maximum": 200, + "minimum": 1, + "format": "int32" } }, { - "name": "published", + "name": "cursor", "in": "query", - "description": "Selects publication presence.", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { - "type": "boolean", - "description": "Selects publication presence." + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, { - "name": "limit", + "name": "actionType", "in": "query", "schema": { - "type": "integer", - "default": 50, - "maximum": 200, - "minimum": 1, - "format": "int32" + "$ref": "#/components/schemas/ProposalActionType" } }, { - "name": "cursor", + "name": "entryKind", "in": "query", "schema": { - "type": "string" + "$ref": "#/components/schemas/EntryType" } } ], "responses": { "200": { - "description": "ListFaqs 200 response", + "description": "ListProposals 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListFaqsResponseContent" + "$ref": "#/components/schemas/ListProposalsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -2267,11 +2639,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -2317,39 +2699,35 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "List FAQs" + } }, - "delete": { - "description": "Deletes the requested FAQ families sequentially. Each family deletion is atomic, but the batch is not: deletions completed before an error remain applied. Retrying the same request is safe because already absent entries are ignored.", - "operationId": "DeleteFaqs", + "post": { + "description": "Submit an FAQ for human review. Extraction and agent submissions share proposalPolicy.maxOpenProposals. When the Inbox is full, HTTP 409 content-limit-exceeded identifies the configured limit and observed open count; the proposal was not saved. Review/dismiss existing proposals or ask an administrator to increase the configured limit before retrying. Capacity is advisory because Search is eventually consistent.", + "operationId": "CreateProposal", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteFaqsRequestContent" + "$ref": "#/components/schemas/CreateProposalRequestContent" } } }, @@ -2369,22 +2747,22 @@ } ], "responses": { - "200": { - "description": "DeleteFaqs 200 response", + "201": { + "description": "CreateProposal 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeleteFaqsResponseContent" + "$ref": "#/components/schemas/CreateProposalResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -2430,11 +2808,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -2480,35 +2868,41 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Delete multiple FAQs" + } } }, - "/v1/playbooks/{playbookId}/faqs/{faqId}": { - "get": { - "operationId": "GetFaq", + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals/search": { + "post": { + "operationId": "SearchProposals", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchProposalsRequestContent" + } + } + }, + "required": true + }, "parameters": [ { "name": "playbookId", @@ -2520,36 +2914,25 @@ "description": "Opaque Playbook identifier." }, "required": true - }, - { - "name": "faqId", - "in": "path", - "description": "Opaque stable entry identifier.", - "schema": { - "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." - }, - "required": true } ], "responses": { "200": { - "description": "GetFaq 200 response", + "description": "SearchProposals 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetFaqResponseContent" + "$ref": "#/components/schemas/SearchProposalsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -2595,11 +2978,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -2645,33 +3038,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Get an FAQ" - }, + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals/{proposalId}": { "delete": { - "operationId": "DeleteFaq", + "operationId": "PurgeProposal", "parameters": [ { "name": "playbookId", @@ -2685,27 +3076,25 @@ "required": true }, { - "name": "faqId", + "name": "proposalId", "in": "path", - "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." + "pattern": "^prp_[0-9a-f]{32}$" }, "required": true } ], "responses": { "204": { - "description": "DeleteFaq 204 response" + "description": "PurgeProposal 204 response" }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -2751,11 +3140,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -2801,45 +3200,29 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Delete an FAQ" - } - }, - "/v1/playbooks/{playbookId}/faqs/{faqId}/versions": { - "post": { - "operationId": "AppendFaqVersion", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AppendFaqVersionRequestContent" - } - } - }, - "required": true - }, + } + }, + "get": { + "operationId": "GetProposal", "parameters": [ { "name": "playbookId", @@ -2853,34 +3236,32 @@ "required": true }, { - "name": "faqId", + "name": "proposalId", "in": "path", - "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." + "pattern": "^prp_[0-9a-f]{32}$" }, "required": true } ], "responses": { - "201": { - "description": "AppendFaqVersion 201 response", + "200": { + "description": "GetProposal 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AppendFaqVersionResponseContent" + "$ref": "#/components/schemas/GetProposalResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -2926,11 +3307,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -2976,33 +3367,39 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Append an FAQ version" + } }, - "get": { - "operationId": "ListFaqVersions", + "patch": { + "operationId": "ReplaceProposal", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReplaceProposalRequestContent" + } + } + }, + "required": true + }, "parameters": [ { "name": "playbookId", @@ -3016,72 +3413,32 @@ "required": true }, { - "name": "faqId", + "name": "proposalId", "in": "path", - "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." + "pattern": "^prp_[0-9a-f]{32}$" }, "required": true - }, - { - "name": "createdAfter", - "in": "query", - "description": "UTC timestamp resolved to microsecond precision.", - "schema": { - "type": "string", - "description": "UTC timestamp resolved to microsecond precision.", - "format": "date-time" - } - }, - { - "name": "createdBefore", - "in": "query", - "description": "UTC timestamp resolved to microsecond precision.", - "schema": { - "type": "string", - "description": "UTC timestamp resolved to microsecond precision.", - "format": "date-time" - } - }, - { - "name": "limit", - "in": "query", - "schema": { - "type": "integer", - "default": 50, - "maximum": 200, - "minimum": 1, - "format": "int32" - } - }, - { - "name": "cursor", - "in": "query", - "schema": { - "type": "string" - } } ], "responses": { "200": { - "description": "ListFaqVersions 200 response", + "description": "ReplaceProposal 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListFaqVersionsResponseContent" + "$ref": "#/components/schemas/ReplaceProposalResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -3127,11 +3484,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -3177,35 +3544,42 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "List FAQ versions" + } } }, - "/v1/playbooks/{playbookId}/faqs/{faqId}/versions/{version}": { - "get": { - "operationId": "GetFaqVersion", + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals/{proposalId}/acceptance": { + "post": { + "description": "Promotes the reviewed revision to one canonical unpublished FAQ.\nConcurrent calls and retries resume or return the proposal's recorded target.\nA complete target may be visible to management before the proposal reaches\npromoted, but remains absent from serving until separately published.", + "operationId": "AcceptProposal", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AcceptProposalRequestContent" + } + } + }, + "required": true + }, "parameters": [ { "name": "playbookId", @@ -3219,44 +3593,32 @@ "required": true }, { - "name": "faqId", - "in": "path", - "description": "Opaque stable entry identifier.", - "schema": { - "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." - }, - "required": true - }, - { - "name": "version", - "in": "path", - "schema": { - "type": "integer", - "minimum": 1, - "format": "int32" + "name": "proposalId", + "in": "path", + "schema": { + "type": "string", + "pattern": "^prp_[0-9a-f]{32}$" }, "required": true } ], "responses": { - "200": { - "description": "GetFaqVersion 200 response", + "201": { + "description": "AcceptProposal 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetFaqVersionResponseContent" + "$ref": "#/components/schemas/AcceptProposalResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -3302,11 +3664,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -3352,46 +3724,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Get an FAQ version" + } } }, - "/v1/playbooks/{playbookId}/faqs/{faqId}/publication": { - "put": { - "description": "Publishes the selected immutable FAQ version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", - "operationId": "PublishFaq", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PublishFaqRequestContent" - } - } - }, - "required": true - }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals/{proposalId}/dismissal": { + "delete": { + "operationId": "RestoreProposal", "parameters": [ { "name": "playbookId", @@ -3405,34 +3762,32 @@ "required": true }, { - "name": "faqId", + "name": "proposalId", "in": "path", - "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." + "pattern": "^prp_[0-9a-f]{32}$" }, "required": true } ], "responses": { "200": { - "description": "PublishFaq 200 response", + "description": "RestoreProposal 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PublishFaqResponseContent" + "$ref": "#/components/schemas/RestoreProposalResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -3478,11 +3833,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -3528,34 +3893,38 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Publish an FAQ version" + } }, - "delete": { - "description": "Withdraws the FAQ publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", - "operationId": "WithdrawFaq", + "put": { + "operationId": "DismissProposal", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DismissProposalRequestContent" + } + } + } + }, "parameters": [ { "name": "playbookId", @@ -3569,34 +3938,32 @@ "required": true }, { - "name": "faqId", + "name": "proposalId", "in": "path", - "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^ent_[0-9a-f]{32}$", - "description": "Opaque stable entry identifier." + "pattern": "^prp_[0-9a-f]{32}$" }, "required": true } ], "responses": { "200": { - "description": "WithdrawFaq 200 response", + "description": "DismissProposal 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WithdrawFaqResponseContent" + "$ref": "#/components/schemas/DismissProposalResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -3642,11 +4009,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -3692,40 +4069,36 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "FAQs" - ], - "summary": "Withdraw an FAQ" + } } }, - "/v1/playbooks/{playbookId}/discover": { - "post": { - "operationId": "DiscoverEntries", + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals/{proposalId}/evidence/{evidenceId}": { + "put": { + "operationId": "SubmitProposalEvidence", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DiscoverEntriesRequestContent" + "$ref": "#/components/schemas/SubmitProposalEvidenceRequestContent" } } }, @@ -3742,25 +4115,43 @@ "description": "Opaque Playbook identifier." }, "required": true + }, + { + "name": "proposalId", + "in": "path", + "schema": { + "type": "string", + "pattern": "^prp_[0-9a-f]{32}$" + }, + "required": true + }, + { + "name": "evidenceId", + "in": "path", + "schema": { + "type": "string", + "pattern": "^evd_[0-9a-f]{32}$" + }, + "required": true } ], "responses": { "200": { - "description": "DiscoverEntries 200 response", + "description": "SubmitProposalEvidence 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DiscoverEntriesResponseContent" + "$ref": "#/components/schemas/SubmitProposalEvidenceResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -3806,11 +4197,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -3856,45 +4257,32 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Retrieval" - ], - "summary": "Discover published entries" + } } }, - "/v1/playbooks/{playbookId}/faqs/search": { - "post": { - "operationId": "SearchFaqs", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchFaqsRequestContent" - } - } - }, - "required": true - }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/proposals/{proposalId}/resources/{resourceId}": { + "get": { + "description": "Returns exact candidate file bytes for the requested proposal revision. A stale revision returns HTTP 412 /errors/revision-conflict; responses must not be cached.", + "operationId": "GetProposalResource", "parameters": [ { "name": "playbookId", @@ -3906,25 +4294,80 @@ "description": "Opaque Playbook identifier." }, "required": true + }, + { + "name": "proposalId", + "in": "path", + "schema": { + "type": "string", + "pattern": "^prp_[0-9a-f]{32}$" + }, + "required": true + }, + { + "name": "resourceId", + "in": "path", + "description": "Opaque immutable Skill resource identifier.", + "schema": { + "type": "string", + "pattern": "^res_[0-9a-f]{24}$", + "description": "Opaque immutable Skill resource identifier." + }, + "required": true + }, + { + "name": "expectedRevision", + "in": "query", + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "schema": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." + }, + "required": true } ], "responses": { "200": { - "description": "SearchFaqs 200 response", + "description": "GetProposalResource 200 response", + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + }, + "required": true + }, + "Content-Digest": { + "description": "SHA-256 content digest using the RFC 9530 Content-Digest representation.", + "schema": { + "type": "string", + "pattern": "^sha-256=:[A-Za-z0-9+/]{43}=:$", + "description": "SHA-256 content digest using the RFC 9530 Content-Digest representation." + }, + "required": true + }, + "Content-Type": { + "schema": { + "type": "string" + }, + "required": true + } + }, "content": { - "application/json": { + "*/*": { "schema": { - "$ref": "#/components/schemas/SearchFaqsResponseContent" + "$ref": "#/components/schemas/GetProposalResourceOutputPayload" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -3970,11 +4413,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -4020,75 +4473,128 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + } + }, + "503": { + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } + } + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills": { + "get": { + "operationId": "ListSkills", + "parameters": [ + { + "name": "playbookId", + "in": "path", + "description": "Opaque Playbook identifier.", + "schema": { + "type": "string", + "pattern": "^pb_[0-9a-f]{32}$", + "description": "Opaque Playbook identifier." + }, + "required": true + }, + { + "name": "sortBy", + "in": "query", + "description": "Default updatedAt descending, then entry ID ascending.", + "schema": { + "$ref": "#/components/schemas/EntrySort" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "Defaults to DESC. ID ties are always ASC.", + "schema": { + "$ref": "#/components/schemas/SortOrder" + } + }, + { + "name": "createdAfter", + "in": "query", + "description": "Exclusive bound at microsecond precision.", + "schema": { + "type": "string", + "description": "Exclusive bound at microsecond precision.", + "format": "date-time" + } + }, + { + "name": "createdBefore", + "in": "query", + "description": "Exclusive bound at microsecond precision.", + "schema": { + "type": "string", + "description": "Exclusive bound at microsecond precision.", + "format": "date-time" + } }, - "503": { - "description": "PlaybookServiceUnavailableError 503 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" - } - } + { + "name": "published", + "in": "query", + "description": "Selects publication presence.", + "schema": { + "type": "boolean", + "description": "Selects publication presence." } - } - }, - "tags": [ - "Retrieval" - ], - "summary": "Search published FAQs" - } - }, - "/v1/playbooks/{playbookId}/skills/search": { - "post": { - "operationId": "SearchSkills", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchSkillsRequestContent" - } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 50, + "maximum": 200, + "minimum": 1, + "format": "int32" } }, - "required": true - }, - "parameters": [ { - "name": "playbookId", - "in": "path", - "description": "Opaque Playbook identifier.", + "name": "cursor", + "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", "schema": { "type": "string", - "pattern": "^pb_[0-9a-f]{32}$", - "description": "Opaque Playbook identifier." - }, - "required": true + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." + } } ], "responses": { "200": { - "description": "SearchSkills 200 response", + "description": "ListSkills 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SearchSkillsResponseContent" + "$ref": "#/components/schemas/ListSkillsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -4134,11 +4640,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -4184,41 +4700,34 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Retrieval" - ], - "summary": "Search published skills" - } - }, - "/v1/playbooks/{playbookId}/entries/lookup": { + } + }, "post": { - "description": "Resolves bounded entry references to compact management state. Results preserve input order and report misses explicitly. Each item is authoritative when read, but the batch is not a global snapshot.", - "operationId": "LookupEntries", + "operationId": "CreateSkill", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/LookupEntriesRequestContent" + "$ref": "#/components/schemas/CreateSkillRequestContent" } } }, @@ -4238,22 +4747,22 @@ } ], "responses": { - "200": { - "description": "LookupEntries 200 response", + "201": { + "description": "CreateSkill 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/LookupEntriesResponseContent" + "$ref": "#/components/schemas/CreateSkillResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -4299,11 +4808,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -4349,40 +4868,37 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Retrieval" - ], - "summary": "Look up entries" + } } }, - "/v1/playbooks/{playbookId}/proposals": { + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/bulk-delete": { "post": { - "operationId": "CreateProposal", + "description": "Deletes the requested Skill families sequentially. Each family deletion is atomic, but the batch is not: a family that cannot be deleted is reported in errors and the others are still processed, and deletions completed before a request-level error remain applied. Retrying the same request is safe because already absent entries are ignored.", + "operationId": "DeleteSkills", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateProposalRequestContent" + "$ref": "#/components/schemas/DeleteSkillsRequestContent" } } }, @@ -4402,22 +4918,22 @@ } ], "responses": { - "201": { - "description": "CreateProposal 201 response", + "200": { + "description": "DeleteSkills 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateProposalResponseContent" + "$ref": "#/components/schemas/DeleteSkillsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -4463,11 +4979,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -4513,33 +5039,41 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/search": { + "post": { + "operationId": "SearchSkills", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchSkillsRequestContent" + } + } + }, + "required": true }, - "tags": [ - "Proposals" - ], - "summary": "Create a proposal" - }, - "get": { - "operationId": "ListProposals", "parameters": [ { "name": "playbookId", @@ -4551,81 +5085,25 @@ "description": "Opaque Playbook identifier." }, "required": true - }, - { - "name": "view", - "in": "query", - "schema": { - "$ref": "#/components/schemas/ProposalView" - }, - "required": true - }, - { - "name": "sortBy", - "in": "query", - "description": "Default updatedAt descending, then proposal ID ascending.", - "schema": { - "$ref": "#/components/schemas/ProposalSort" - } - }, - { - "name": "sortOrder", - "in": "query", - "description": "Defaults to asc for deadlines, desc otherwise. ID ties are always asc.", - "schema": { - "$ref": "#/components/schemas/SortOrder" - } - }, - { - "name": "limit", - "in": "query", - "schema": { - "type": "integer", - "default": 50, - "maximum": 200, - "minimum": 1, - "format": "int32" - } - }, - { - "name": "cursor", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "actionType", - "in": "query", - "schema": { - "$ref": "#/components/schemas/ProposalActionType" - } - }, - { - "name": "entryType", - "in": "query", - "schema": { - "$ref": "#/components/schemas/EntryType" - } } ], "responses": { "200": { - "description": "ListProposals 200 response", + "description": "SearchSkills 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListProposalsResponseContent" + "$ref": "#/components/schemas/SearchSkillsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -4671,11 +5149,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -4721,45 +5209,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "List proposals" + } } }, - "/v1/playbooks/{playbookId}/proposals/{proposalId}/evidence/{evidenceId}": { - "put": { - "operationId": "SubmitProposalEvidence", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SubmitProposalEvidenceRequestContent" - } - } - }, - "required": true - }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/{skillId}": { + "delete": { + "operationId": "DeleteSkill", "parameters": [ { "name": "playbookId", @@ -4773,41 +5247,27 @@ "required": true }, { - "name": "proposalId", - "in": "path", - "schema": { - "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" - }, - "required": true - }, - { - "name": "evidenceId", + "name": "skillId", "in": "path", + "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^evd_[0-9a-f]{32}$" + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." }, "required": true } ], "responses": { - "200": { - "description": "SubmitProposalEvidence 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SubmitProposalEvidenceResponseContent" - } - } - } + "204": { + "description": "DeleteSkill 204 response" }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -4853,11 +5313,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -4903,45 +5373,29 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" - } - } - } - } - }, - "tags": [ - "Proposals" - ], - "summary": "Submit proposal evidence" - } - }, - "/v1/playbooks/{playbookId}/proposals/search": { - "post": { - "operationId": "SearchProposals", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchProposalsRequestContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } } } - }, - "required": true - }, + } + } + }, + "get": { + "operationId": "GetSkill", "parameters": [ { "name": "playbookId", @@ -4953,25 +5407,36 @@ "description": "Opaque Playbook identifier." }, "required": true + }, + { + "name": "skillId", + "in": "path", + "description": "Opaque stable entry identifier.", + "schema": { + "type": "string", + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." + }, + "required": true } ], "responses": { "200": { - "description": "SearchProposals 200 response", + "description": "GetSkill 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SearchProposalsResponseContent" + "$ref": "#/components/schemas/GetSkillResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -5017,11 +5482,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -5067,35 +5542,32 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Search proposals" + } } }, - "/v1/playbooks/{playbookId}/proposals/{proposalId}": { - "get": { - "operationId": "GetProposal", + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/{skillId}/publication": { + "delete": { + "description": "Withdraws the Skill publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", + "operationId": "WithdrawSkill", "parameters": [ { "name": "playbookId", @@ -5109,32 +5581,34 @@ "required": true }, { - "name": "proposalId", + "name": "skillId", "in": "path", + "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." }, "required": true } ], "responses": { "200": { - "description": "GetProposal 200 response", + "description": "WithdrawSkill 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetProposalResponseContent" + "$ref": "#/components/schemas/WithdrawSkillResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -5180,11 +5654,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -5230,38 +5714,35 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Get a proposal" + } }, - "patch": { - "operationId": "ReplaceProposal", + "put": { + "description": "Publishes the selected immutable Skill version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.", + "operationId": "PublishSkill", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ReplaceProposalRequestContent" + "$ref": "#/components/schemas/PublishSkillRequestContent" } } }, @@ -5280,32 +5761,34 @@ "required": true }, { - "name": "proposalId", + "name": "skillId", "in": "path", + "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." }, "required": true } ], "responses": { "200": { - "description": "ReplaceProposal 200 response", + "description": "PublishSkill 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ReplaceProposalResponseContent" + "$ref": "#/components/schemas/PublishSkillResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -5351,11 +5834,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -5401,33 +5894,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Replace a proposal candidate" - }, - "delete": { - "operationId": "PurgeProposal", + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/{skillId}/versions": { + "get": { + "operationId": "ListSkillVersions", "parameters": [ { "name": "playbookId", @@ -5441,25 +5932,76 @@ "required": true }, { - "name": "proposalId", + "name": "skillId", "in": "path", + "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." }, "required": true + }, + { + "name": "createdAfter", + "in": "query", + "description": "UTC timestamp resolved to microsecond precision.", + "schema": { + "type": "string", + "description": "UTC timestamp resolved to microsecond precision.", + "format": "date-time" + } + }, + { + "name": "createdBefore", + "in": "query", + "description": "UTC timestamp resolved to microsecond precision.", + "schema": { + "type": "string", + "description": "UTC timestamp resolved to microsecond precision.", + "format": "date-time" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 50, + "maximum": 200, + "minimum": 1, + "format": "int32" + } + }, + { + "name": "cursor", + "in": "query", + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`.", + "schema": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." + } } ], "responses": { - "204": { - "description": "PurgeProposal 204 response" + "200": { + "description": "ListSkillVersions 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListSkillVersionsResponseContent" + } + } + } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -5505,11 +6047,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -5555,41 +6107,34 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Purge a proposal" - } - }, - "/v1/playbooks/{playbookId}/proposals/{proposalId}/acceptance": { + } + }, "post": { - "description": "Promotes the reviewed revision to one canonical unpublished FAQ.\nConcurrent calls and retries resume or return the proposal's recorded target.\nA complete target may be visible to management before the proposal reaches\npromoted, but remains absent from serving until separately published.", - "operationId": "AcceptProposal", + "operationId": "AppendSkillVersion", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AcceptProposalRequestContent" + "$ref": "#/components/schemas/AppendSkillVersionRequestContent" } } }, @@ -5608,32 +6153,34 @@ "required": true }, { - "name": "proposalId", + "name": "skillId", "in": "path", + "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." }, "required": true } ], "responses": { "201": { - "description": "AcceptProposal 201 response", + "description": "AppendSkillVersion 201 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AcceptProposalResponseContent" + "$ref": "#/components/schemas/AppendSkillVersionResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -5679,11 +6226,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -5729,44 +6286,31 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Accept a reviewed proposal" + } } }, - "/v1/playbooks/{playbookId}/proposals/{proposalId}/dismissal": { - "put": { - "operationId": "DismissProposal", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DismissProposalRequestContent" - } - } - } - }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/{skillId}/versions/{version}": { + "get": { + "operationId": "GetSkillVersion", "parameters": [ { "name": "playbookId", @@ -5780,32 +6324,44 @@ "required": true }, { - "name": "proposalId", + "name": "skillId", "in": "path", + "description": "Opaque stable entry identifier.", "schema": { "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." + }, + "required": true + }, + { + "name": "version", + "in": "path", + "schema": { + "type": "integer", + "minimum": 1, + "format": "int32" }, "required": true } ], "responses": { "200": { - "description": "DismissProposal 200 response", + "description": "GetSkillVersion 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DismissProposalResponseContent" + "$ref": "#/components/schemas/GetSkillVersionResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -5851,11 +6407,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -5901,33 +6467,32 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Dismiss a proposal" - }, - "delete": { - "operationId": "RestoreProposal", + } + } + }, + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/{skillId}/versions/{version}/resources/{resourceId}": { + "get": { + "description": "Returns the exact immutable Skill resource bytes. The Content-Digest response header carries their SHA-256 digest using RFC 9530 syntax.", + "operationId": "GetSkillResource", "parameters": [ { "name": "playbookId", @@ -5941,32 +6506,72 @@ "required": true }, { - "name": "proposalId", + "name": "skillId", + "in": "path", + "description": "Opaque stable entry identifier.", + "schema": { + "type": "string", + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." + }, + "required": true + }, + { + "name": "version", + "in": "path", + "schema": { + "type": "integer", + "minimum": 1, + "format": "int32" + }, + "required": true + }, + { + "name": "resourceId", "in": "path", + "description": "Opaque immutable Skill resource identifier.", "schema": { "type": "string", - "pattern": "^prp_[0-9a-f]{32}$" + "pattern": "^res_[0-9a-f]{24}$", + "description": "Opaque immutable Skill resource identifier." }, "required": true } ], "responses": { "200": { - "description": "RestoreProposal 200 response", + "description": "GetSkillResource 200 response", + "headers": { + "Content-Digest": { + "description": "SHA-256 content digest using the RFC 9530 Content-Digest representation.", + "schema": { + "type": "string", + "pattern": "^sha-256=:[A-Za-z0-9+/]{43}=:$", + "description": "SHA-256 content digest using the RFC 9530 Content-Digest representation." + }, + "required": true + }, + "Content-Type": { + "schema": { + "type": "string" + }, + "required": true + } + }, "content": { - "application/json": { + "*/*": { "schema": { - "$ref": "#/components/schemas/RestoreProposalResponseContent" + "$ref": "#/components/schemas/GetSkillResourceOutputPayload" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -6012,11 +6617,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -6062,35 +6677,32 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Proposals" - ], - "summary": "Restore a proposal" + } } }, - "/v1/playbooks/{playbookId}/health": { + "/iris/data/v1/agent-playbooks/playbooks/{playbookId}/stats": { "get": { - "operationId": "GetPlaybookHealth", + "description": "Returns independent best-effort indexed observations using content-read permissions.\nIndexing delay, expiry and concurrent writes can make counts differ from list results\nor prevent publication buckets from summing to the total. This is not an atomic\nsnapshot or a receipt of entries deleted by clear or bulk delete.", + "operationId": "GetPlaybookStats", "parameters": [ { "name": "playbookId", @@ -6102,25 +6714,78 @@ "description": "Opaque Playbook identifier." }, "required": true + }, + { + "name": "published", + "in": "query", + "description": "Applies only to FAQ/Skill inventory. Intersects each publication bucket.", + "schema": { + "type": "boolean", + "description": "Applies only to FAQ/Skill inventory. Intersects each publication bucket." + } + }, + { + "name": "createdAfter", + "in": "query", + "description": "Applies only to FAQ/Skill inventory; exclusive microsecond bound.", + "schema": { + "type": "string", + "description": "Applies only to FAQ/Skill inventory; exclusive microsecond bound.", + "format": "date-time" + } + }, + { + "name": "createdBefore", + "in": "query", + "description": "Applies only to FAQ/Skill inventory; exclusive microsecond bound.", + "schema": { + "type": "string", + "description": "Applies only to FAQ/Skill inventory; exclusive microsecond bound.", + "format": "date-time" + } + }, + { + "name": "view", + "in": "query", + "description": "Applies only to proposals. Omit to observe both Inbox and Trash.", + "schema": { + "$ref": "#/components/schemas/ProposalView" + } + }, + { + "name": "actionType", + "in": "query", + "description": "Applies only to proposals, matching ListProposals selectors.", + "schema": { + "$ref": "#/components/schemas/ProposalActionType" + } + }, + { + "name": "entryKind", + "in": "query", + "description": "Applies only to proposals, matching ListProposals selectors.", + "schema": { + "$ref": "#/components/schemas/EntryType" + } } ], "responses": { "200": { - "description": "GetPlaybookHealth 200 response", + "description": "GetPlaybookStats 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetPlaybookHealthResponseContent" + "$ref": "#/components/schemas/GetPlaybookStatsResponseContent" } } } }, "400": { - "description": "RequestValidationError 400 response", + "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestValidationErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } } @@ -6166,11 +6831,21 @@ } }, "409": { - "description": "PlaybookConflictError 409 response", + "description": "ConflictError 409 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + } + }, + "412": { + "description": "PreconditionFailedError 412 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookConflictErrorResponseContent" + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" } } } @@ -6216,30 +6891,26 @@ } }, "500": { - "description": "PlaybookInternalError 500 response", + "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookInternalErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } } }, "503": { - "description": "PlaybookServiceUnavailableError 503 response", + "description": "ServiceUnavailableError 503 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } } } - }, - "tags": [ - "Maintenance" - ], - "summary": "Check playbook health" + } } } }, @@ -6248,14 +6919,15 @@ "AcceptProposalRequestContent": { "type": "object", "properties": { - "expectedProposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "expectedRevision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." } }, "required": [ - "expectedProposalRevision" + "expectedRevision" ] }, "AcceptProposalResponseContent": { @@ -6347,7 +7019,8 @@ "packageBase64": { "type": "string", "maxLength": 6990508, - "minLength": 1 + "minLength": 1, + "description": "Base64-encoded ZIP with exactly one enclosing Skill directory. Place SKILL.md directly inside it, for example demo/SKILL.md, and put all resources beneath demo/. The SKILL.md frontmatter name must match the directory name. A flat ZIP with SKILL.md at archive root is not supported. Invalid layout returns HTTP 400 with an errors entry pointing to /packageBase64." }, "content": { "$ref": "#/components/schemas/ContentMetadata" @@ -6429,7 +7102,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "At most five unique intents, each 1 through 2,048 characters after normalization. Omission is an empty list. Validation failures identify this member in the HTTP 400 errors array." }, "attributes": { "$ref": "#/components/schemas/AttributeMap" @@ -6445,6 +7119,94 @@ "payload" ] }, + "BadRequestErrorResponseContent": { + "type": "object", + "description": "Request validation or input decoding failed.", + "properties": { + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + }, + "status": { + "type": "integer", + "default": 400, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32" + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem." + }, + "instance": { + "type": "string", + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + }, + "type": { + "$ref": "#/components/schemas/BadRequestErrorType" + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FieldError" + }, + "description": "Every invalid request member found, when the failure is about members." + } + }, + "required": [ + "status", + "title", + "type" + ] + }, + "BadRequestErrorType": { + "type": "string", + "description": "Problem type URI for bad request errors.", + "enum": [ + "/errors/invalid-data", + "/errors/invalid-cursor", + "/errors/unknown-request-member", + "/errors/invalid-model-config", + "/errors/model-config-immutable", + "/errors/model-config-not-supported" + ] + }, + "BulkDeleteEntryError": { + "type": "object", + "description": "Why one entry of a bulk delete was not deleted, as RFC 9457 problem fields.", + "properties": { + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + }, + "status": { + "type": "integer", + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32" + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem." + }, + "instance": { + "type": "string", + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + }, + "entryId": { + "type": "string", + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." + }, + "type": { + "type": "string" + } + }, + "required": [ + "entryId", + "status", + "title", + "type" + ] + }, "CandidatePreviewContent": { "type": "object", "properties": { @@ -6472,9 +7234,82 @@ "required": [ "faq" ] + }, + { + "type": "object", + "title": "skill", + "properties": { + "skill": { + "$ref": "#/components/schemas/SkillCandidatePreview" + } + }, + "required": [ + "skill" + ] } ] }, + "ConflictErrorResponseContent": { + "type": "object", + "description": "The request conflicts with the current state of the resource.", + "properties": { + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + }, + "status": { + "type": "integer", + "default": 409, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32" + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem." + }, + "instance": { + "type": "string", + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + }, + "type": { + "$ref": "#/components/schemas/ConflictErrorType" + }, + "existingId": { + "type": "string", + "description": "The ID of the existing resource the request collided with, when the conflict names one." + } + }, + "required": [ + "status", + "title", + "type" + ] + }, + "ConflictErrorType": { + "type": "string", + "description": "Problem type URI for conflict errors.", + "enum": [ + "/errors/conflict", + "/errors/entry-not-published", + "/errors/entry-key-conflict", + "/errors/content-limit-exceeded", + "/errors/pinned-entry-unavailable", + "/errors/proposal-already-exists", + "/errors/proposal-evidence-conflict", + "/errors/proposal-evidence-capacity", + "/errors/proposal-trashed", + "/errors/proposal-open", + "/errors/proposal-promotion-locked", + "/errors/extraction-disabled", + "/errors/gateway-mutation-in-progress", + "/errors/surface-mutation-in-progress", + "/errors/namespace-conflict", + "/errors/gateway-not-empty", + "/errors/gateway-deleting", + "/errors/catalog-publication-conflict", + "/errors/summary-view-conflict" + ] + }, "ContentMetadata": { "type": "object", "description": "Author-provided context shared by FAQ, Skill and proposal authoring.", @@ -6487,7 +7322,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "At most five unique intents, each 1 through 2,048 characters after normalization. Omission is an empty list. Validation failures identify this member in the HTTP 400 errors array." }, "attributes": { "$ref": "#/components/schemas/AttributeMap" @@ -6509,7 +7345,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "At most five unique intents, each 1 through 2,048 characters after normalization. Omission is an empty list. Validation failures identify this member in the HTTP 400 errors array." }, "attributes": { "$ref": "#/components/schemas/AttributeMap" @@ -6579,18 +7416,19 @@ "type": "string", "pattern": "^prp_[0-9a-f]{32}$" }, - "status": { - "$ref": "#/components/schemas/ProposalStatus" + "state": { + "$ref": "#/components/schemas/ProposalState" }, "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Present for actions that author content; absent for candidate-free actions." }, - "proposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "revision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "evidenceCount": { "type": "integer", @@ -6643,9 +7481,9 @@ "evidenceCount", "inboxExpiresAt", "proposalId", - "proposalRevision", "purgeAt", - "status", + "revision", + "state", "updatedAt" ] }, @@ -6655,7 +7493,8 @@ "packageBase64": { "type": "string", "maxLength": 6990508, - "minLength": 1 + "minLength": 1, + "description": "Base64-encoded ZIP with exactly one enclosing Skill directory. Place SKILL.md directly inside it, for example demo/SKILL.md, and put all resources beneath demo/. The SKILL.md frontmatter name must match the directory name. A flat ZIP with SKILL.md at archive root is not supported. Invalid layout returns HTTP 400 with an errors entry pointing to /packageBase64." }, "content": { "$ref": "#/components/schemas/ContentMetadata" @@ -6709,14 +7548,28 @@ "DeleteFaqsResponseContent": { "type": "object", "properties": { - "deletedEntriesCount": { - "type": "integer", - "description": "Number of entries removed by this successful attempt. Entries already absent at\nthe start of the attempt are ignored and do not contribute to the count.", - "format": "int32" + "deleted": { + "type": "array", + "items": { + "type": "string", + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." + }, + "maxItems": 100, + "description": "Entries removed by this successful attempt. Entries already absent at the start\nof the attempt are ignored and are not listed, so a retry can return an empty list." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BulkDeleteEntryError" + }, + "maxItems": 100, + "description": "Requested entries this attempt did not delete, one problem each; the other entries\nwere still processed. Empty when every entry was deleted or already absent. Retry\nthe listed entries." } }, "required": [ - "deletedEntriesCount" + "deleted", + "errors" ] }, "DeleteSkillsRequestContent": { @@ -6741,14 +7594,28 @@ "DeleteSkillsResponseContent": { "type": "object", "properties": { - "deletedEntriesCount": { - "type": "integer", - "description": "Number of entries removed by this successful attempt. Entries already absent at\nthe start of the attempt are ignored and do not contribute to the count.", - "format": "int32" + "deleted": { + "type": "array", + "items": { + "type": "string", + "pattern": "^ent_[0-9a-f]{32}$", + "description": "Opaque stable entry identifier." + }, + "maxItems": 100, + "description": "Entries removed by this successful attempt. Entries already absent at the start\nof the attempt are ignored and are not listed, so a retry can return an empty list." + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BulkDeleteEntryError" + }, + "maxItems": 100, + "description": "Requested entries this attempt did not delete, one problem each; the other entries\nwere still processed. Empty when every entry was deleted or already absent. Retry\nthe listed entries." } }, "required": [ - "deletedEntriesCount" + "deleted", + "errors" ] }, "DiscoverEntriesRequestContent": { @@ -6827,7 +7694,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "version": { @@ -6843,7 +7710,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "Zero through five unique intent strings. Each intent contains 1 through 2,048 characters after normalization. Invalid lists return HTTP 400 with an errors entry pointing to the invalid intents member." }, "faq": { "$ref": "#/components/schemas/FaqContent" @@ -6856,13 +7724,13 @@ "maximum": 1, "minimum": 0, "description": "Normalized cosine similarity: (2 - Redis cosine distance) / 2.", - "format": "float" + "format": "double" } }, "required": [ "entryId", - "entryType", "intents", + "kind", "score", "version" ] @@ -6870,11 +7738,11 @@ "DismissProposalRequestContent": { "type": "object", "properties": { - "expectedProposalRevision": { - "type": "integer", - "minimum": 1, - "description": "Optional revision check for an open proposal; omission dismisses the current\ncandidate regardless of revision. A mismatch returns ProposalRevisionConflict.\nDismissal preserves the candidate for restoration; an already trashed proposal\nis a successful no-op regardless of the supplied revision.", - "format": "int32" + "expectedRevision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Optional revision check for an open proposal; omission dismisses the current\ncandidate regardless of revision. A mismatch returns 412 /errors/revision-conflict.\nDismissal preserves the candidate for restoration; an already trashed proposal\nis a successful no-op regardless of the supplied revision." } } }, @@ -6885,18 +7753,19 @@ "type": "string", "pattern": "^prp_[0-9a-f]{32}$" }, - "status": { - "$ref": "#/components/schemas/ProposalStatus" + "state": { + "$ref": "#/components/schemas/ProposalState" }, "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Present for actions that author content; absent for candidate-free actions." }, - "proposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "revision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "evidenceCount": { "type": "integer", @@ -6949,9 +7818,9 @@ "evidenceCount", "inboxExpiresAt", "proposalId", - "proposalRevision", "purgeAt", - "status", + "revision", + "state", "updatedAt" ] }, @@ -6998,7 +7867,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latest": { @@ -7015,7 +7884,7 @@ }, "required": [ "entryId", - "entryType", + "kind", "latest", "versionCount" ] @@ -7049,7 +7918,7 @@ ] }, "EntryReference": { - "description": "One discovery pin. Smithy unions enforce exactly one identifier.", + "description": "One discovery pin. Exactly one identifier must be set.", "oneOf": [ { "type": "object", @@ -7094,8 +7963,8 @@ "EntryType": { "type": "string", "enum": [ - "faq", - "skill" + "FAQ", + "SKILL" ] }, "EntryVersionDigest": { @@ -7193,7 +8062,9 @@ "description": "Problem type URI for failed-dependency errors.", "enum": [ "/errors/resource-unavailable", - "/errors/database-out-of-memory" + "/errors/database-out-of-memory", + "/errors/invalid-model-credentials", + "/errors/model-quota-exceeded" ] }, "FaqAuthoredContent": { @@ -7208,7 +8079,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "At most five unique intents, each 1 through 2,048 characters after normalization. Omission is an empty list. Validation failures identify this member in the HTTP 400 errors array." }, "attributes": { "$ref": "#/components/schemas/AttributeMap" @@ -7275,25 +8147,23 @@ }, "FieldError": { "type": "object", - "description": "Validation error details for a single request field.", + "description": "One invalid request member. A body member is named by `pointer`, a path or query parameter by `parameter`; exactly one of the two is present.", "properties": { - "field": { + "pointer": { "type": "string", - "description": "Name of the invalid request field." + "description": "JSON Pointer (RFC 6901) to the invalid body member, such as `/vectorSpace/dimensions`." }, - "rule": { + "parameter": { "type": "string", - "description": "Validation rule that was violated." + "description": "Name of the invalid path or query parameter, such as `limit`." }, - "message": { + "detail": { "type": "string", - "description": "Human-readable validation error message." + "description": "What is wrong with the member, in fixed words about the rule it broke, never the rejected value." } }, "required": [ - "field", - "message", - "rule" + "detail" ] }, "Filter": { @@ -7414,7 +8284,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -7440,7 +8310,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -7453,7 +8323,7 @@ "pattern": "^ent_[0-9a-f]{32}$", "description": "Opaque stable entry identifier." }, - "entryType": { + "entryKind": { "$ref": "#/components/schemas/EntryType" }, "version": { @@ -7480,7 +8350,7 @@ "contentDigest", "createdAt", "entryId", - "entryType", + "entryKind", "version" ] }, @@ -7517,6 +8387,35 @@ "status" ] }, + "GetPlaybookStatsResponseContent": { + "type": "object", + "properties": { + "observedAt": { + "type": "string", + "description": "Observation start in UTC, also used to evaluate proposal lifecycle deadlines.\nIndividual queries may complete later; this does not imply snapshot isolation.", + "format": "date-time" + }, + "faqs": { + "$ref": "#/components/schemas/InventoryStats" + }, + "skills": { + "$ref": "#/components/schemas/InventoryStats" + }, + "proposals": { + "$ref": "#/components/schemas/ProposalStats" + } + }, + "required": [ + "faqs", + "observedAt", + "proposals", + "skills" + ] + }, + "GetProposalResourceOutputPayload": { + "type": "string", + "format": "binary" + }, "GetProposalResponseContent": { "type": "object", "properties": { @@ -7524,18 +8423,19 @@ "type": "string", "pattern": "^prp_[0-9a-f]{32}$" }, - "status": { - "$ref": "#/components/schemas/ProposalStatus" + "state": { + "$ref": "#/components/schemas/ProposalState" }, "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Present for actions that author content; absent for candidate-free actions." }, - "proposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "revision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "evidenceCount": { "type": "integer", @@ -7588,9 +8488,9 @@ "evidenceCount", "inboxExpiresAt", "proposalId", - "proposalRevision", "purgeAt", - "status", + "revision", + "state", "updatedAt" ] }, @@ -7613,7 +8513,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -7639,7 +8539,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -7652,7 +8552,7 @@ "pattern": "^ent_[0-9a-f]{32}$", "description": "Opaque stable entry identifier." }, - "entryType": { + "entryKind": { "$ref": "#/components/schemas/EntryType" }, "version": { @@ -7679,25 +8579,48 @@ "contentDigest", "createdAt", "entryId", - "entryType", + "entryKind", "version" ] }, + "InventoryStats": { + "type": "object", + "description": "Each bucket intersects all requested inventory filters.", + "properties": { + "total": { + "$ref": "#/components/schemas/ObservedCount" + }, + "published": { + "$ref": "#/components/schemas/ObservedCount" + }, + "unpublished": { + "$ref": "#/components/schemas/ObservedCount" + } + }, + "required": [ + "published", + "total", + "unpublished" + ] + }, "ListFaqVersionsResponseContent": { "type": "object", "properties": { - "versions": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } }, "nextCursor": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ - "versions" + "items" ] }, "ListFaqsResponseContent": { @@ -7705,15 +8628,11 @@ "properties": { "nextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Continue until nextCursor is absent, including after short or empty pages.\nLive updates/indexing delay can repeat or skip moved items; this is not a snapshot." }, - "total": { - "type": "integer", - "minimum": 0, - "description": "First-page count matching the original filters at count-query time. Omitted on\ncursored requests or when counting is unavailable; absence means unknown, not zero.", - "format": "int32" - }, - "faqs": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/StableEntry" @@ -7721,7 +8640,7 @@ } }, "required": [ - "faqs" + "items" ] }, "ListProposalsResponseContent": { @@ -7729,15 +8648,11 @@ "properties": { "nextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Continue until nextCursor is absent, including after short or empty pages.\nLive updates/indexing delay can repeat or skip moved items; this is not a snapshot." }, - "total": { - "type": "integer", - "minimum": 0, - "description": "First-page count matching the original filters at count-query time. Omitted on\ncursored requests or when counting is unavailable; absence means unknown, not zero.", - "format": "int32" - }, - "proposals": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalPreview" @@ -7745,24 +8660,27 @@ } }, "required": [ - "proposals" + "items" ] }, "ListSkillVersionsResponseContent": { "type": "object", "properties": { - "versions": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } }, "nextCursor": { - "type": "string" + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque position in a list, returned as `nextCursor` and passed back as `cursor`." } }, "required": [ - "versions" + "items" ] }, "ListSkillsResponseContent": { @@ -7770,15 +8688,11 @@ "properties": { "nextCursor": { "type": "string", + "maxLength": 1024, + "minLength": 1, "description": "Continue until nextCursor is absent, including after short or empty pages.\nLive updates/indexing delay can repeat or skip moved items; this is not a snapshot." }, - "total": { - "type": "integer", - "minimum": 0, - "description": "First-page count matching the original filters at count-query time. Omitted on\ncursored requests or when counting is unavailable; absence means unknown, not zero.", - "format": "int32" - }, - "skills": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/StableEntry" @@ -7786,7 +8700,7 @@ } }, "required": [ - "skills" + "items" ] }, "LookupEntriesRequestContent": { @@ -7809,7 +8723,7 @@ "LookupEntriesResponseContent": { "type": "object", "properties": { - "results": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/EntryLookupResult" @@ -7822,8 +8736,8 @@ } }, "required": [ - "maxVersions", - "results" + "items", + "maxVersions" ] }, "MissingEntryLookupResult": { @@ -7885,7 +8799,26 @@ "type": "string", "description": "Problem type URI for not-found errors.", "enum": [ - "/errors/resource-not-found" + "/errors/resource-not-found", + "/errors/gateway-not-found", + "/errors/upstream-not-found" + ] + }, + "ObservedCount": { + "type": "object", + "description": "A successful empty query has available=true and value=0. Failed, timed-out,\npartial or malformed counts have available=false and no value.", + "properties": { + "available": { + "type": "boolean" + }, + "value": { + "type": "integer", + "minimum": 0, + "format": "int64" + } + }, + "required": [ + "available" ] }, "PayloadTooLargeErrorResponseContent": { @@ -7929,7 +8862,7 @@ }, "PinnedPlaybookPreviewEntry": { "type": "object", - "description": "Flat preview wire shape. Exactly one of faq or skill is present and matches entryType.", + "description": "Flat preview wire shape. Exactly one of faq or skill is present and matches kind.", "properties": { "entryId": { "type": "string", @@ -7943,7 +8876,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "version": { @@ -7959,7 +8892,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "Zero through five unique intent strings. Each intent contains 1 through 2,048 characters after normalization. Invalid lists return HTTP 400 with an errors entry pointing to the invalid intents member." }, "faq": { "$ref": "#/components/schemas/FaqContent" @@ -7970,74 +8904,14 @@ }, "required": [ "entryId", - "entryType", "intents", + "kind", "version" ] }, - "PlaybookConflictErrorResponseContent": { - "type": "object", - "description": "One schema per HTTP status preserves the complete problem catalog in generated\nclients, following the Iris/Agent Memory dedicated error-type enum pattern.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 409, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/PlaybookConflictErrorType" - }, - "existingProposalId": { - "type": "string", - "pattern": "^prp_[0-9a-f]{32}$", - "description": "Present for proposal-already-exists. Identifies the retained duplicate." - }, - "currentProposalRevision": { - "type": "integer", - "minimum": 1, - "description": "Present when proposal-revision-conflict reports the current candidate revision.", - "format": "int32" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "PlaybookConflictErrorType": { - "type": "string", - "description": "Distinguish resource state conflicts by type, never by human-readable title.", - "enum": [ - "/errors/entry-not-published", - "/errors/entry-key-conflict", - "/errors/content-limit-exceeded", - "/errors/pinned-entry-unavailable", - "/errors/proposal-already-exists", - "/errors/proposal-evidence-conflict", - "/errors/proposal-evidence-capacity", - "/errors/proposal-revision-conflict", - "/errors/proposal-trashed", - "/errors/proposal-open", - "/errors/proposal-promotion-locked" - ] - }, - "PlaybookInternalErrorResponseContent": { + "PreconditionFailedErrorResponseContent": { "type": "object", - "description": "Stored integrity failures require operator investigation; editing or blindly\nretrying the request does not repair the stored record.", + "description": "The write named an expected revision (expectedRevision or If-Match) that is no longer current. Read the resource again and retry.", "properties": { "title": { "type": "string", @@ -8045,7 +8919,7 @@ }, "status": { "type": "integer", - "default": 500, + "default": 412, "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", "format": "int32" }, @@ -8058,47 +8932,11 @@ "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." }, "type": { - "$ref": "#/components/schemas/PlaybookInternalErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "PlaybookInternalErrorType": { - "type": "string", - "description": "Server faults are distinct from correctable resource-state conflicts.", - "enum": [ - "/errors/unexpected-error", - "/errors/content-integrity-failed" - ] - }, - "PlaybookServiceUnavailableErrorResponseContent": { - "type": "object", - "description": "Retry reads and proposal acceptance with bounded backoff. Acceptance resumes\nits recorded canonical target. An uncertain create or append response may have\nwritten another logical record or version and should not be blindly retried\nwhen the caller requires exactly one result.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 503, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." + "$ref": "#/components/schemas/PreconditionFailedErrorType" }, - "instance": { + "currentRevision": { "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/PlaybookServiceUnavailableErrorType" + "description": "The resource's current revision, when the service reports it. Read the resource again before retrying; do not send this value back without reading." } }, "required": [ @@ -8107,11 +8945,11 @@ "type" ] }, - "PlaybookServiceUnavailableErrorType": { + "PreconditionFailedErrorType": { "type": "string", + "description": "Problem type URI for a write whose expected revision is no longer current. A write guarded by an If-Match header on an HTTP entity tag uses a different type; see the Identity Service API.", "enum": [ - "/errors/service-unavailable", - "/errors/playbook-not-ready" + "/errors/revision-conflict" ] }, "PreviewPayload": { @@ -8212,15 +9050,15 @@ "ProposalActionType": { "type": "string", "enum": [ - "add" + "ADD" ] }, "ProposalCandidate": { "type": "object", - "description": "Complete suggested authored content. Resource URIs are derived on output.", + "description": "Complete normalized candidate. Proposal resources have no entry-version URI.", "properties": { "content": { - "$ref": "#/components/schemas/AuthoredContent" + "$ref": "#/components/schemas/ProposalContent" } }, "required": [ @@ -8229,7 +9067,7 @@ }, "ProposalCandidateInput": { "type": "object", - "description": "Launch proposal authoring accepts FAQ content only.", + "description": "Proposal authoring accepts FAQ content or a complete Skill ZIP.", "properties": { "content": { "$ref": "#/components/schemas/ProposalInputContent" @@ -8250,6 +9088,35 @@ "content" ] }, + "ProposalContent": { + "type": "object", + "description": "Author-provided context shared by FAQ, Skill and proposal authoring.", + "properties": { + "intents": { + "type": "array", + "items": { + "type": "string", + "maxLength": 2048, + "minLength": 1 + }, + "maxItems": 5, + "uniqueItems": true, + "description": "At most five unique intents, each 1 through 2,048 characters after normalization. Omission is an empty list. Validation failures identify this member in the HTTP 400 errors array." + }, + "attributes": { + "$ref": "#/components/schemas/AttributeMap" + }, + "metadata": { + "description": "Author-provided JSON metadata. Its normalized JSON encoding must not exceed 65,536 bytes or nesting depth 16; deployments may enforce lower limits. Exceeding the byte limit returns payload-too-large, while excessive nesting returns invalid-data." + }, + "payload": { + "$ref": "#/components/schemas/ProposalPayload" + } + }, + "required": [ + "payload" + ] + }, "ProposalEvidence": { "type": "object", "description": "Immutable reviewer context relevant to the proposal's underlying need. An\nobservation may disagree with the proposed answer; it is not a vote or proof.\nEvidence survives candidate edits and is never copied into an accepted entry.", @@ -8281,8 +9148,8 @@ "ProposalEvidenceDisposition": { "type": "string", "enum": [ - "added", - "alreadyPresent" + "ADDED", + "ALREADY_PRESENT" ] }, "ProposalInputContent": { @@ -8297,7 +9164,8 @@ "minLength": 1 }, "maxItems": 5, - "uniqueItems": true + "uniqueItems": true, + "description": "At most five unique intents, each 1 through 2,048 characters after normalization. Omission is an empty list. Validation failures identify this member in the HTTP 400 errors array." }, "attributes": { "$ref": "#/components/schemas/AttributeMap" @@ -8313,8 +9181,37 @@ "payload" ] }, - "ProposalInputPayload": { - "description": "Launch accepts FAQ only; future package inputs add their own members.", + "ProposalInputPayload": { + "oneOf": [ + { + "type": "object", + "title": "faq", + "properties": { + "faq": { + "$ref": "#/components/schemas/FaqContent" + } + }, + "required": [ + "faq" + ], + "additionalProperties": false + }, + { + "type": "object", + "title": "skillPackage", + "properties": { + "skillPackage": { + "$ref": "#/components/schemas/ProposalSkillPackage" + } + }, + "required": [ + "skillPackage" + ], + "additionalProperties": false + } + ] + }, + "ProposalPayload": { "oneOf": [ { "type": "object", @@ -8326,8 +9223,19 @@ }, "required": [ "faq" - ], - "additionalProperties": false + ] + }, + { + "type": "object", + "title": "skill", + "properties": { + "skill": { + "$ref": "#/components/schemas/ProposalSkillContent" + } + }, + "required": [ + "skill" + ] } ] }, @@ -8339,18 +9247,19 @@ "type": "string", "pattern": "^prp_[0-9a-f]{32}$" }, - "status": { - "$ref": "#/components/schemas/ProposalStatus" + "state": { + "$ref": "#/components/schemas/ProposalState" }, "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Present for actions that author content; absent for candidate-free actions." }, - "proposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "revision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "evidenceCount": { "type": "integer", @@ -8389,12 +9298,85 @@ "evidenceCount", "inboxExpiresAt", "proposalId", - "proposalRevision", "purgeAt", - "status", + "revision", + "state", "updatedAt" ] }, + "ProposalResource": { + "type": "object", + "properties": { + "resourceId": { + "type": "string" + }, + "path": { + "type": "string" + }, + "digest": { + "type": "string", + "pattern": "^sha256:[0-9a-f]{64}$", + "description": "SHA-256 digest of exact resource bytes in sha256: form." + }, + "sizeBytes": { + "type": "integer", + "format": "int64" + }, + "mimeType": { + "type": "string" + }, + "executable": { + "type": "boolean" + } + }, + "required": [ + "digest", + "executable", + "mimeType", + "path", + "resourceId", + "sizeBytes" + ] + }, + "ProposalSkillContent": { + "type": "object", + "properties": { + "format": { + "$ref": "#/components/schemas/SkillFormat" + }, + "manifest": { + "$ref": "#/components/schemas/SkillManifest" + }, + "instructions": { + "type": "string" + }, + "resources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProposalResource" + } + } + }, + "required": [ + "format", + "instructions", + "manifest", + "resources" + ] + }, + "ProposalSkillPackage": { + "type": "object", + "properties": { + "packageBase64": { + "type": "string", + "maxLength": 6990508, + "minLength": 1 + } + }, + "required": [ + "packageBase64" + ] + }, "ProposalSort": { "type": "string", "enum": [ @@ -8408,9 +9390,9 @@ }, "ProposalSource": { "type": "object", - "description": "Caller-supplied origin and observed material, not verified attribution.\nOn a proposal this is immutable creation context, excluded from evidenceCount.\nOn evidence this describes an additional observation relevant to the same need.\nReference locates the input; content preserves the submitter's observation or\nexcerpt. Both, when present, must be JSON objects. Their fields are source-specific.\nRAM extraction uses agent-memory-session or agent-memory-summary references and\nquestionAnswer content; its question/answer are model-derived, not verbatim events.\nSee docs/specs/MOD-18196-playbook-extraction-readiness-follow-up.md for that contract.", + "description": "Caller-supplied origin and observed material, not verified attribution.\nOn a proposal this is immutable creation context, excluded from evidenceCount.\nOn evidence this describes an additional observation relevant to the same need.\nReference locates the input; content preserves the submitter's observation or\nexcerpt. Both, when present, must be JSON objects. Their fields are source-specific.\nAgent Memory extraction uses agent-memory-session or agent-memory-summary references and\nquestionAnswer content; its question/answer are model-derived, not verbatim events.", "properties": { - "type": { + "kind": { "type": "string", "maxLength": 128, "minLength": 1 @@ -8419,18 +9401,29 @@ "content": {} }, "required": [ - "type" + "kind" ] }, - "ProposalStatus": { + "ProposalState": { "type": "string", "enum": [ - "open", - "trashed", - "promoting", - "promoted" + "OPEN", + "TRASHED", + "PROMOTING", + "PROMOTED" ] }, + "ProposalStats": { + "type": "object", + "properties": { + "inbox": { + "$ref": "#/components/schemas/ObservedCount" + }, + "trash": { + "$ref": "#/components/schemas/ObservedCount" + } + } + }, "ProposalTarget": { "description": "Exactly one target. Launch supports creating a new entry.", "oneOf": [ @@ -8474,7 +9467,7 @@ "pattern": "^ent_[0-9a-f]{32}$", "description": "Opaque stable entry identifier." }, - "entryType": { + "entryKind": { "$ref": "#/components/schemas/EntryType" }, "version": { @@ -8491,15 +9484,15 @@ "required": [ "contentDigest", "entryId", - "entryType", + "entryKind", "version" ] }, "ProposalView": { "type": "string", "enum": [ - "inbox", - "trash" + "INBOX", + "TRASH" ] }, "Publication": { @@ -8553,7 +9546,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -8579,7 +9572,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -8612,7 +9605,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -8638,7 +9631,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -8646,7 +9639,7 @@ "ReadyStatus": { "type": "string", "enum": [ - "ready" + "READY" ] }, "ReplaceProposalRequestContent": { @@ -8655,15 +9648,16 @@ "action": { "$ref": "#/components/schemas/ProposalActionInput" }, - "expectedProposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "expectedRevision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." } }, "required": [ "action", - "expectedProposalRevision" + "expectedRevision" ] }, "ReplaceProposalResponseContent": { @@ -8673,18 +9667,19 @@ "type": "string", "pattern": "^prp_[0-9a-f]{32}$" }, - "status": { - "$ref": "#/components/schemas/ProposalStatus" + "state": { + "$ref": "#/components/schemas/ProposalState" }, "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Present for actions that author content; absent for candidate-free actions." }, - "proposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "revision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "evidenceCount": { "type": "integer", @@ -8737,60 +9732,12 @@ "evidenceCount", "inboxExpiresAt", "proposalId", - "proposalRevision", "purgeAt", - "status", + "revision", + "state", "updatedAt" ] }, - "RequestValidationErrorResponseContent": { - "type": "object", - "description": "One HTTP 400 schema preserves every validation problem type in generated clients.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 400, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/RequestValidationErrorType" - }, - "fields": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FieldError" - }, - "description": "Optional field-level validation details, as in the shared Iris BadRequestError." - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "RequestValidationErrorType": { - "type": "string", - "description": "Machine-readable validation failure; SDKs branch on type, never title text.", - "enum": [ - "/errors/invalid-data", - "/errors/invalid-cursor", - "/errors/unknown-request-member" - ] - }, "ResourceDescriptor": { "type": "object", "properties": { @@ -8878,18 +9825,19 @@ "type": "string", "pattern": "^prp_[0-9a-f]{32}$" }, - "status": { - "$ref": "#/components/schemas/ProposalStatus" + "state": { + "$ref": "#/components/schemas/ProposalState" }, "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Present for actions that author content; absent for candidate-free actions." }, - "proposalRevision": { - "type": "integer", - "minimum": 1, - "format": "int32" + "revision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional." }, "evidenceCount": { "type": "integer", @@ -8942,9 +9890,9 @@ "evidenceCount", "inboxExpiresAt", "proposalId", - "proposalRevision", "purgeAt", - "status", + "revision", + "state", "updatedAt" ] }, @@ -8958,7 +9906,8 @@ "type": "number", "maximum": 1, "minimum": 0, - "format": "float" + "description": "A relevance score in [0, 1]. Higher is closer, and every threshold in the API\n(`minScore`) points the same way: higher is stricter.", + "format": "double" } }, "required": [ @@ -8977,12 +9926,12 @@ "filter": { "$ref": "#/components/schemas/Filter" }, - "minimumScore": { + "minScore": { "type": "number", "maximum": 1, "minimum": 0, "description": "Normalized cosine similarity floor applied to this request. Omission uses the corresponding FAQ or Skill discovery threshold.", - "format": "float" + "format": "double" }, "limit": { "type": "integer", @@ -8999,7 +9948,7 @@ "SearchFaqsResponseContent": { "type": "object", "properties": { - "matches": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveredPlaybookPreviewEntry" @@ -9007,7 +9956,7 @@ } }, "required": [ - "matches" + "items" ] }, "SearchProposalsRequestContent": { @@ -9016,7 +9965,7 @@ "actionType": { "$ref": "#/components/schemas/ProposalActionType" }, - "entryType": { + "entryKind": { "$ref": "#/components/schemas/EntryType" }, "query": { @@ -9024,11 +9973,12 @@ "maxLength": 4096, "minLength": 1 }, - "minimumScore": { + "minScore": { "type": "number", "maximum": 1, "minimum": 0, - "format": "float" + "description": "A relevance score in [0, 1]. Higher is closer, and every threshold in the API\n(`minScore`) points the same way: higher is stricter.", + "format": "double" }, "limit": { "type": "integer", @@ -9046,7 +9996,7 @@ "SearchProposalsResponseContent": { "type": "object", "properties": { - "matches": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScoredProposalPreview" @@ -9054,7 +10004,7 @@ } }, "required": [ - "matches" + "items" ] }, "SearchSkillsRequestContent": { @@ -9068,12 +10018,12 @@ "filter": { "$ref": "#/components/schemas/Filter" }, - "minimumScore": { + "minScore": { "type": "number", "maximum": 1, "minimum": 0, "description": "Normalized cosine similarity floor applied to this request. Omission uses the corresponding FAQ or Skill discovery threshold.", - "format": "float" + "format": "double" }, "limit": { "type": "integer", @@ -9090,7 +10040,7 @@ "SearchSkillsResponseContent": { "type": "object", "properties": { - "matches": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveredPlaybookPreviewEntry" @@ -9098,7 +10048,61 @@ } }, "required": [ - "matches" + "items" + ] + }, + "ServiceUnavailableErrorResponseContent": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + }, + "status": { + "type": "integer", + "default": 503, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32" + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem." + }, + "instance": { + "type": "string", + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + }, + "type": { + "$ref": "#/components/schemas/ServiceUnavailableErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ] + }, + "ServiceUnavailableErrorType": { + "type": "string", + "enum": [ + "/errors/service-unavailable", + "/errors/playbook-not-ready", + "/errors/resource-unavailable" + ] + }, + "SkillCandidatePreview": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "required": [ + "description", + "name" ] }, "SkillContent": { @@ -9200,8 +10204,8 @@ "SortOrder": { "type": "string", "enum": [ - "asc", - "desc" + "ASC", + "DESC" ] }, "StableEntry": { @@ -9219,7 +10223,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -9245,7 +10249,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -9378,6 +10382,46 @@ "/errors/too-many-requests" ] }, + "UnexpectedErrorResponseContent": { + "type": "object", + "description": "The service failed with an unexpected internal error.", + "properties": { + "title": { + "type": "string", + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + }, + "status": { + "type": "integer", + "default": 500, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32" + }, + "detail": { + "type": "string", + "description": "A human-readable explanation specific to this occurrence of the problem." + }, + "instance": { + "type": "string", + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + }, + "type": { + "$ref": "#/components/schemas/UnexpectedErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ] + }, + "UnexpectedErrorType": { + "type": "string", + "description": "Problem type URI for unexpected internal errors.", + "enum": [ + "/errors/unexpected-error", + "/errors/content-integrity-failed" + ] + }, "Version": { "type": "object", "properties": { @@ -9386,7 +10430,7 @@ "pattern": "^ent_[0-9a-f]{32}$", "description": "Opaque stable entry identifier." }, - "entryType": { + "entryKind": { "$ref": "#/components/schemas/EntryType" }, "version": { @@ -9413,7 +10457,7 @@ "contentDigest", "createdAt", "entryId", - "entryType", + "entryKind", "version" ] }, @@ -9432,7 +10476,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -9458,7 +10502,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -9478,7 +10522,7 @@ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional Playbook-unique immutable human-readable entry key." }, - "entryType": { + "kind": { "$ref": "#/components/schemas/EntryType" }, "latestVersion": { @@ -9504,7 +10548,7 @@ "required": [ "createdAt", "entryId", - "entryType", + "kind", "latestVersion", "updatedAt" ] @@ -9522,22 +10566,5 @@ { "smithy.api.httpBearerAuth": [] } - ], - "tags": [ - { - "name": "Skills" - }, - { - "name": "FAQs" - }, - { - "name": "Retrieval" - }, - { - "name": "Proposals" - }, - { - "name": "Maintenance" - } ] } diff --git a/content/develop/ai/context-engine/lens/api-reference/openapi.json b/content/develop/ai/context-engine/lens/api-reference/openapi.json index 88c4b871ae..64969e890f 100644 --- a/content/develop/ai/context-engine/lens/api-reference/openapi.json +++ b/content/develop/ai/context-engine/lens/api-reference/openapi.json @@ -6,7 +6,7 @@ "description": "Read-only session and turn API for an Iris Lens instance." }, "paths": { - "/v1/instances/{instanceId}/agents": { + "/iris/data/v1beta1/lens/instances/{instanceId}/agents": { "get": { "description": "Lists every agent with at least one retained session, sorted by agent ID. The list spans all retained sessions regardless of range, so a selector can offer any agent the instance can show sessions for. An instance with no sessions returns an empty list.", "operationId": "ListAgents", @@ -96,7 +96,7 @@ } } }, - "/v1/instances/{instanceId}/sessions": { + "/iris/data/v1beta1/lens/instances/{instanceId}/sessions": { "get": { "description": "Lists sessions for one agent in newest-activity-first order. Pagination fixes the first page's last-seen upper bound but does not materialize an immutable snapshot: concurrent activity can move sessions out of the remaining result set or change their relative order. Start a new traversal to obtain the current view. A cursor is valid only with the same effective filters used to create it; a mismatch returns BadRequestError.", "operationId": "ListSessions", @@ -174,13 +174,13 @@ { "name": "limit", "in": "query", - "description": "Maximum rows returned. The server always supplies this value to RediSearch LIMIT.", + "description": "Maximum rows returned.", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1, - "description": "Maximum rows returned. The server always supplies this value to RediSearch LIMIT.", + "description": "Maximum rows returned.", "format": "int32" } }, @@ -271,7 +271,7 @@ } } }, - "/v1/instances/{instanceId}/sessions/{sessionId}": { + "/iris/data/v1beta1/lens/instances/{instanceId}/sessions/{sessionId}": { "get": { "description": "Returns the retained turns and outcome facets for a session.", "operationId": "GetSession", @@ -371,7 +371,7 @@ } } }, - "/v1/instances/{instanceId}/turns/{turnId}": { + "/iris/data/v1beta1/lens/instances/{instanceId}/turns/{turnId}": { "get": { "description": "Returns one turn. turnId is the turn's OTel trace ID; Lens defines no separate turn identifier.", "operationId": "GetTurn", @@ -470,7 +470,7 @@ } } }, - "/v1/instances/{instanceId}/turns/{turnId}/content/{hash}": { + "/iris/data/v1beta1/lens/instances/{instanceId}/turns/{turnId}/content/{hash}": { "get": { "description": "Returns captured content for one turn hash. Before reading the content tier, the service MUST load the addressed turn, verify that the turn references the requested hash, and enforce the turn's logical content expiry. A missing reference or expired logical reference returns a successful expired response with no body, so callers cannot distinguish expiration from a hash that was never stored.", "operationId": "GetContent", @@ -578,7 +578,7 @@ } } }, - "/v1/instances/{instanceId}/turns/{turnId}/tools/{spanId}/result": { + "/iris/data/v1beta1/lens/instances/{instanceId}/turns/{turnId}/tools/{spanId}/result": { "get": { "description": "Classifies only the captured result owned by the addressed Context Retriever span. Authorization, span ownership, and content expiry are enforced before loading the body.", "operationId": "GetContextRetrieverResult", @@ -691,7 +691,7 @@ "schemas": { "Agent": { "type": "object", - "description": "One agent an instance has seen, identified by its raw iris.agent.id. A display label is not part of this contract yet; see the TDD's agents-seen record for the planned telemetry-sourced label.", + "description": "One agent an instance has seen, identified by its raw iris.agent.id.", "properties": { "agentId": { "type": "string", @@ -888,12 +888,12 @@ "type": { "$ref": "#/components/schemas/BadRequestErrorType" }, - "fields": { + "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" }, - "description": "Optional field-level validation errors." + "description": "Every invalid request member found, when the failure is about members." } }, "required": [ @@ -906,16 +906,21 @@ "type": "string", "description": "Problem type URI for bad request errors.", "enum": [ - "/errors/invalid-data" + "/errors/invalid-data", + "/errors/invalid-cursor", + "/errors/unknown-request-member", + "/errors/invalid-model-config", + "/errors/model-config-immutable", + "/errors/model-config-not-supported" ] }, "ComponentCallOutcome": { "type": "string", "enum": [ - "ok", - "failed", - "cancelled", - "unknown" + "OK", + "FAILED", + "CANCELLED", + "UNKNOWN" ] }, "ComponentOperation": { @@ -926,7 +931,7 @@ "pattern": "^[0-9a-f]{16}$" }, "component": { - "type": "string" + "$ref": "#/components/schemas/ToolComponent" }, "operation": { "type": "string", @@ -976,26 +981,26 @@ "ContentAvailability": { "type": "string", "enum": [ - "available", - "expired", - "masked", - "not-captured", - "fetch-failed" + "AVAILABLE", + "EXPIRED", + "MASKED", + "NOT_CAPTURED", + "FETCH_FAILED" ] }, "ContentKind": { "type": "string", "enum": [ - "prompt", - "completion", - "tool-arguments", - "tool-result", - "retrieval-document", - "recalled-memory", - "playbook-entry", - "playbook-snapshot", - "memory-snapshot", - "component-input" + "PROMPT", + "COMPLETION", + "TOOL_ARGUMENTS", + "TOOL_RESULT", + "RETRIEVAL_DOCUMENT", + "RECALLED_MEMORY", + "PLAYBOOK_ENTRY", + "PLAYBOOK_SNAPSHOT", + "MEMORY_SNAPSHOT", + "COMPONENT_INPUT" ] }, "ContentReference": { @@ -1111,8 +1116,7 @@ "description": "The retrieval span this entry came from, so a reader can place it in the span tree." }, "component": { - "type": "string", - "description": "The component that served the retrieval, from iris.component.name." + "$ref": "#/components/schemas/ToolComponent" }, "operation": { "type": "string", @@ -1231,11 +1235,11 @@ "ContextRetrieverClassification": { "type": "string", "enum": [ - "unavailable", - "unclassified", - "records", - "aggregate", - "tool-error" + "UNAVAILABLE", + "UNCLASSIFIED", + "RECORDS", + "AGGREGATE", + "TOOL_ERROR" ] }, "ContextRetrieverProvenance": { @@ -1318,33 +1322,31 @@ "ContextUsageState": { "type": "string", "enum": [ - "entered-prompt", - "fetched-not-used", - "invoked-empty", - "not-instrumented" + "ENTERED_PROMPT", + "FETCHED_NOT_USED", + "INVOKED_EMPTY", + "NOT_INSTRUMENTED" ] }, "FieldError": { "type": "object", - "description": "Validation error details for a single request field.", + "description": "One invalid request member. A body member is named by `pointer`, a path or query parameter by `parameter`; exactly one of the two is present.", "properties": { - "field": { + "pointer": { "type": "string", - "description": "Name of the invalid request field." + "description": "JSON Pointer (RFC 6901) to the invalid body member, such as `/vectorSpace/dimensions`." }, - "rule": { + "parameter": { "type": "string", - "description": "Validation rule that was violated." + "description": "Name of the invalid path or query parameter, such as `limit`." }, - "message": { + "detail": { "type": "string", - "description": "Human-readable validation error message." + "description": "What is wrong with the member, in fixed words about the rule it broke, never the rejected value." } }, "required": [ - "field", - "message", - "rule" + "detail" ] }, "ForbiddenErrorResponseContent": { @@ -1433,17 +1435,17 @@ "description": "Nonnegative recorded integer in the exact JavaScript integer range.", "format": "int64" }, - "resultCacheStatus": { + "cacheStatus": { "type": "string", "maxLength": 512, "minLength": 1, - "description": "hit when the Gateway reports a result cache hit. Absence does not imply a miss." + "description": "hit when the Gateway reports a cache hit. Absence does not imply a miss." }, - "resultCacheAgeMs": { + "cacheAgeMs": { "type": "integer", "maximum": 9007199254740991, "minimum": 0, - "description": "Age of the cached result, present only with resultCacheStatus hit.", + "description": "Age of the cached result, present only with cacheStatus hit.", "format": "int64" }, "failureReason": { @@ -1471,33 +1473,33 @@ "description": "Recorded signed integer in the exact JavaScript integer range.", "format": "int64" }, - "resultHandleRef": { + "handleRef": { "type": "string", "maxLength": 16, "minLength": 16, "pattern": "^[0-9a-f]{16}$", "description": "Non-capability correlation reference, never a raw handle ID." }, - "resultHandleShape": { + "handleShape": { "type": "string", "maxLength": 512, "minLength": 1, "description": "Recorded result shape: collection, document, or text." }, - "resultHandleCompleteness": { + "handleCompleteness": { "type": "string", "maxLength": 512, "minLength": 1, "description": "Recorded result completeness: complete, partial, or unknown." }, - "resultHandleBytes": { + "handleBytes": { "type": "integer", "maximum": 9007199254740991, "minimum": 0, "description": "Nonnegative recorded integer in the exact JavaScript integer range.", "format": "int64" }, - "resultHandleItems": { + "handleItems": { "type": "integer", "maximum": 9007199254740991, "minimum": 0, @@ -1807,7 +1809,9 @@ "type": "string", "description": "Problem type URI for not-found errors.", "enum": [ - "/errors/resource-not-found" + "/errors/resource-not-found", + "/errors/gateway-not-found", + "/errors/upstream-not-found" ] }, "OutcomeFacetCount": { @@ -1986,7 +1990,7 @@ "pattern": "^[0-9a-f]{16}$" }, "component": { - "type": "string" + "$ref": "#/components/schemas/ToolComponent" }, "operation": { "type": "string" @@ -2043,11 +2047,11 @@ "type": "string", "description": "NOT_AVAILABLE: the source was asked and returned no score, as every Agent Memory recall does today. UNSCORED: the caller never supplied one. Neither is a low score.", "enum": [ - "high", - "medium", - "low", - "unscored", - "not-available" + "HIGH", + "MEDIUM", + "LOW", + "UNSCORED", + "NOT_AVAILABLE" ] }, "ServiceUnavailableErrorResponseContent": { @@ -2084,7 +2088,9 @@ "ServiceUnavailableErrorType": { "type": "string", "enum": [ - "/errors/service-unavailable" + "/errors/service-unavailable", + "/errors/playbook-not-ready", + "/errors/resource-unavailable" ] }, "SessionListItem": { @@ -2154,22 +2160,22 @@ "type": "string", "description": "Session-level OR facet. UNSET represents turns that did not record iris.turn.outcome.", "enum": [ - "completed", - "failed", - "abandoned", - "refused", - "timeout", - "unset" + "COMPLETED", + "FAILED", + "ABANDONED", + "REFUSED", + "TIMEOUT", + "UNSET" ] }, "SpanKind": { "type": "string", "enum": [ - "internal", - "server", - "client", - "producer", - "consumer" + "INTERNAL", + "SERVER", + "CLIENT", + "PRODUCER", + "CONSUMER" ] }, "SpanNode": { @@ -2242,9 +2248,9 @@ "SpanStatus": { "type": "string", "enum": [ - "unset", - "ok", - "error" + "UNSET", + "OK", + "ERROR" ] }, "TokenUsage": { @@ -2274,20 +2280,21 @@ }, "ToolComponent": { "type": "string", + "description": "The Iris component a call belongs to. Every turn member named component uses it.", "enum": [ - "agent_memory", - "playbook", - "context_retriever", - "context_gateway" + "AGENT_MEMORY", + "PLAYBOOK", + "CONTEXT_RETRIEVER", + "CONTEXT_GATEWAY" ] }, "ToolOutcome": { "type": "string", - "description": "ok means the call returned and does not assert tool success, including an MCP isError result without a Gateway failure entry. A Gateway failure entry can make it failed. Lens keeps the producer's outcome, including invalid_arguments recorded as ok.", + "description": "OK means the call returned and does not assert tool success, including an MCP isError result without a Gateway failure entry. A Gateway failure entry can make it FAILED. Lens keeps the producer's outcome, including invalid_arguments recorded as OK.", "enum": [ - "ok", - "failed", - "cancelled" + "OK", + "FAILED", + "CANCELLED" ] }, "ToolSpan": { @@ -2321,11 +2328,11 @@ "TurnOutcome": { "type": "string", "enum": [ - "completed", - "failed", - "abandoned", - "refused", - "timeout" + "COMPLETED", + "FAILED", + "ABANDONED", + "REFUSED", + "TIMEOUT" ] }, "TurnSummary": { @@ -2418,9 +2425,22 @@ "type": "string", "description": "Problem type URI for unexpected internal errors.", "enum": [ - "/errors/unexpected-error" + "/errors/unexpected-error", + "/errors/content-integrity-failed" ] } + }, + "securitySchemes": { + "smithy.api.httpBearerAuth": { + "type": "http", + "description": "HTTP Bearer authentication", + "scheme": "Bearer" + } + } + }, + "security": [ + { + "smithy.api.httpBearerAuth": [] } - } + ] } diff --git a/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json b/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json index 88849785f9..38bb023b3a 100644 --- a/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json +++ b/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json @@ -1,2646 +1,4623 @@ { - "openapi": "3.0.2", - "info": { - "title": "Redis Agent Memory Control Plane API", - "version": "1.0.0", - "description": "Admin API for the Redis Agent Memory self-managed Control Plane.\n\nAuthentication: management endpoints require an operator credential. By default, use a static admin token, sent as\n`Authorization: Bearer `. The header and scheme are configurable with\n`auth.admin_token.header` and `auth.admin_token.scheme`; the security scheme shown is the\ndefault. Configured OIDC operator tokens are also accepted. The admin token is distinct from the agent keys used by the Data Plane. Operational\nendpoints (health, build-info) are served separately and are unauthenticated.\n\nThere is no per-store database, subscription, or endpoint binding: self-managed deployments use\na single shared store database. Embedding configuration is resolved server-side from deployment\nconfig rather than supplied here.\n" - }, - "paths": { - "/v1/detectors": { - "get": { - "description": "List the built-in sensitive-data detectors a store may select in its\n`longTermMemoryExclusions.builtInDetectors` configuration.\n\nThis is the only supported way to discover which detector ids exist. Use this\nendpoint rather than a fixed list: a selection naming an id this endpoint does not\nlist is rejected on write.\n\nThis is read-only reference data with no store scope. Listing a detector does not\nenable it; selecting one is a store configuration change.", - "operationId": "ListBuiltInDetectors", - "responses": { - "200": { - "description": "ListBuiltInDetectors 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListBuiltInDetectorsResponseContent" - } - } - } + "components": { + "schemas": { + "AuthenticationErrorResponseContent": { + "description": "Authentication credentials are missing, malformed, or invalid.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 401, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/AuthenticationErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "AuthenticationErrorType": { + "description": "Problem type URI for authentication errors.", + "enum": [ + "/errors/authentication-failed" + ], + "type": "string" + }, + "BadRequestErrorResponseContent": { + "description": "Request validation or input decoding failed.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "errors": { + "description": "Every invalid request member found, when the failure is about members.", + "items": { + "$ref": "#/components/schemas/FieldError" + }, + "type": "array" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 400, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/BadRequestErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "BadRequestErrorType": { + "description": "Problem type URI for bad request errors.", + "enum": [ + "/errors/invalid-data", + "/errors/invalid-cursor", + "/errors/unknown-request-member", + "/errors/invalid-model-config", + "/errors/model-config-immutable", + "/errors/model-config-not-supported" + ], + "type": "string" + }, + "BuiltInDetector": { + "description": "One selectable built-in detector.", + "properties": { + "description": { + "description": "What the detector matches, and what it does not.", + "type": "string" + }, + "id": { + "description": "The detector identifier, as accepted in a store's exclusions configuration.", + "type": "string" + }, + "name": { + "description": "Human-readable detector name, for display.", + "type": "string" + } + }, + "required": [ + "description", + "id", + "name" + ], + "type": "object" + }, + "BuiltInDetectorsConfig": { + "description": "Selection of platform built-in detectors for a store. Nothing is selected by\ndefault.", + "properties": { + "detectors": { + "description": "The selected detectors.", + "items": { + "$ref": "#/components/schemas/DetectorSelection" + }, + "type": "array" + }, + "enabled": { + "description": "Toggle for the whole built-in group. False keeps the selections stored but\ninactive.", + "type": "boolean" + } + }, + "required": [ + "enabled" + ], + "type": "object" + }, + "ConflictErrorResponseContent": { + "description": "The request conflicts with the current state of the resource.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "existingId": { + "description": "The ID of the existing resource the request collided with, when the conflict names one.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 409, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ConflictErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "ConflictErrorType": { + "description": "Problem type URI for conflict errors.", + "enum": [ + "/errors/conflict", + "/errors/entry-not-published", + "/errors/entry-key-conflict", + "/errors/content-limit-exceeded", + "/errors/pinned-entry-unavailable", + "/errors/proposal-already-exists", + "/errors/proposal-evidence-conflict", + "/errors/proposal-evidence-capacity", + "/errors/proposal-trashed", + "/errors/proposal-open", + "/errors/proposal-promotion-locked", + "/errors/extraction-disabled", + "/errors/gateway-mutation-in-progress", + "/errors/surface-mutation-in-progress", + "/errors/namespace-conflict", + "/errors/gateway-not-empty", + "/errors/gateway-deleting", + "/errors/catalog-publication-conflict", + "/errors/summary-view-conflict" + ], + "type": "string" + }, + "CreateExtractorRequestContent": { + "properties": { + "destinationNamespaceId": { + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "type": "string" + }, + "enabled": { + "default": true, + "type": "boolean" + }, + "memoryType": { + "description": "Must be a memory type registered on the store.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + }, + "name": { + "description": "Display name of any API resource.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "prompt": { + "type": "string" + }, + "source": { + "$ref": "#/components/schemas/ExtractorSource" + }, + "strategy": { + "$ref": "#/components/schemas/ExtractorStrategy" + } + }, + "required": [ + "memoryType", + "name", + "prompt", + "source", + "strategy" + ], + "type": "object" + }, + "CreateExtractorResponseContent": { + "properties": { + "createdAt": { + "format": "date-time", + "type": "string" + }, + "destinationNamespaceId": { + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "extractorId": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" + }, + "memoryType": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + }, + "name": { + "description": "Display name of any API resource.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "prompt": { + "type": "string" + }, + "revision": { + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "maxLength": 64, + "minLength": 1, + "type": "string" + }, + "source": { + "$ref": "#/components/schemas/ExtractorSource" + }, + "strategy": { + "$ref": "#/components/schemas/ExtractorStrategy" + }, + "updatedAt": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "createdAt", + "enabled", + "extractorId", + "memoryType", + "name", + "prompt", + "revision", + "source", + "strategy", + "updatedAt" + ], + "type": "object" + }, + "CreateMemoryTypeResponseContent": { + "description": "A custom memory type registered on a store: a named category of long-term memory\nwith its structured fields and, optionally, an extraction strategy.", + "properties": { + "description": { + "description": "Human-readable description of what this memory type captures.", + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/CustomExtractionStrategy" + }, + "fields": { + "description": "Structured fields that make up a record of this type. Optional; a type with no\nfields accepts direct writes carrying no structured attributes.", + "items": { + "$ref": "#/components/schemas/CustomField" + }, + "type": "array" + }, + "name": { + "description": "Unique type name within the store. Must not collide with built-in types\n(semantic, episodic, message, session_summary, session_summary_view).", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "required": [ + "description", + "name" + ], + "type": "object" + }, + "CreateStoreRequestContent": { + "properties": { + "customMemoryTypes": { + "description": "Custom memory types to register on the store. Optional; when omitted the\nstore uses only built-in memory types.", + "items": { + "$ref": "#/components/schemas/CustomMemoryType" + }, + "type": "array" + }, + "database": { + "$ref": "#/components/schemas/DatabaseRef" + }, + "extractionCadence": { + "$ref": "#/components/schemas/ExtractionCadenceConfig" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/ExtractionStrategy" + }, + "longTermMemory": { + "$ref": "#/components/schemas/LongTermMemoryConfigInput" + }, + "longTermMemoryExclusions": { + "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + }, + "name": { + "description": "The name of the memory store.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "shortMemory": { + "$ref": "#/components/schemas/ShortMemoryConfigInput" + }, + "summarization": { + "$ref": "#/components/schemas/SummarizationConfig" + } + }, + "required": [ + "database", + "name" + ], + "type": "object" + }, + "CreateStoreResponseContent": { + "description": "Memory store configuration and status.", + "properties": { + "createdAt": { + "description": "The UTC timestamp when the memory store was created.", + "format": "date-time", + "type": "string" + }, + "database": { + "$ref": "#/components/schemas/StoreDatabase" + }, + "endpoints": { + "description": "Redis Cloud only. API endpoints for accessing the memory store.", + "items": { + "$ref": "#/components/schemas/StoreEndpoint" + }, + "type": "array", + "x-deployment": "cloud" + }, + "extractionCadence": { + "$ref": "#/components/schemas/ExtractionCadenceConfig" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/ExtractionStrategy" + }, + "failure": { + "$ref": "#/components/schemas/StoreFailure" + }, + "longTermMemory": { + "$ref": "#/components/schemas/LongTermMemoryConfigStatus" + }, + "longTermMemoryExclusions": { + "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + }, + "name": { + "description": "Human-readable name of the memory store.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "shortMemory": { + "$ref": "#/components/schemas/ShortMemoryConfigStatus" + }, + "state": { + "$ref": "#/components/schemas/ResourceState" + }, + "storeId": { + "description": "Unique identifier for the memory store.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + }, + "subscriptionId": { + "description": "Redis Cloud only. The memory store's database subscription ID.", + "type": "string", + "x-deployment": "cloud" + }, + "summarization": { + "$ref": "#/components/schemas/SummarizationConfig" + } + }, + "required": [ + "createdAt", + "database", + "extractionStrategy", + "longTermMemory", + "name", + "state", + "storeId" + ], + "type": "object" + }, + "CustomDetector": { + "description": "One customer-authored detector.", + "properties": { + "action": { + "$ref": "#/components/schemas/ExclusionAction" + }, + "enabled": { + "description": "Whether this detector is active.", + "type": "boolean" + }, + "matcher": { + "$ref": "#/components/schemas/MatcherSpec" + }, + "name": { + "description": "Identifies the detector wherever a match of it is reported.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "required": [ + "enabled", + "matcher", + "name" + ], + "type": "object" + }, + "CustomDetectorsConfig": { + "description": "Customer-authored detectors for a store. Evaluated together with the built-in\ndetectors. Nothing is defined by default.", + "properties": { + "detectors": { + "description": "At most 32. Names must be unique within the store and must not be a built-in\ndetector id.", + "items": { + "$ref": "#/components/schemas/CustomDetector" + }, + "type": "array" + }, + "enabled": { + "description": "Toggle for the whole custom group. False keeps the detectors stored but\ninactive.", + "type": "boolean" + } + }, + "required": [ + "enabled" + ], + "type": "object" + }, + "CustomExtractionStrategy": { + "description": "Extraction strategy for a custom memory type.", + "properties": { + "enabled": { + "description": "Whether the strategy is active. Defaults to true when omitted.", + "type": "boolean" + }, + "prompt": { + "description": "Prompt used to extract memories of this type from session events.", + "type": "string" + } + }, + "required": [ + "prompt" + ], + "type": "object" + }, + "CustomExtractionStrategyUpdate": { + "description": "A change to a memory type's extraction strategy. Omitted members are unchanged.", + "properties": { + "enabled": { + "description": "Replacement enabled flag.", + "type": "boolean" + }, + "prompt": { + "description": "Replacement extraction prompt.", + "type": "string" + } + }, + "type": "object" + }, + "CustomField": { + "description": "A structured field within a custom memory type.", + "properties": { + "description": { + "description": "Human-readable description of the field.", + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + "name": { + "description": "Field name.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/CustomFieldType" + } + }, + "required": [ + "description", + "name", + "type" + ], + "type": "object" + }, + "CustomFieldType": { + "description": "Supported custom field data types.", + "enum": [ + "STRING", + "INTEGER", + "FLOAT", + "BOOLEAN", + "STRING_LIST", + "FLOAT_LIST", + "OBJECT" + ], + "type": "string" + }, + "CustomMemoryType": { + "description": "A custom memory type registered on a store: a named category of long-term memory\nwith its structured fields and, optionally, an extraction strategy.", + "properties": { + "description": { + "description": "Human-readable description of what this memory type captures.", + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/CustomExtractionStrategy" + }, + "fields": { + "description": "Structured fields that make up a record of this type. Optional; a type with no\nfields accepts direct writes carrying no structured attributes.", + "items": { + "$ref": "#/components/schemas/CustomField" + }, + "type": "array" + }, + "name": { + "description": "Unique type name within the store. Must not collide with built-in types\n(semantic, episodic, message, session_summary, session_summary_view).", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "required": [ + "description", + "name" + ], + "type": "object" + }, + "DatabaseRef": { + "description": "The database to store memory data in.", + "properties": { + "databaseId": { + "description": "The database ID.", + "maxLength": 32, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "databaseId" + ], + "type": "object" + }, + "DetectorSelection": { + "description": "One selected built-in detector.", + "properties": { + "action": { + "$ref": "#/components/schemas/ExclusionAction" + }, + "enabled": { + "description": "Whether this detector is active.", + "type": "boolean" + }, + "id": { + "description": "The built-in detector id, as listed by ListBuiltInDetectors.", + "type": "string" + } + }, + "required": [ + "enabled", + "id" + ], + "type": "object" + }, + "ExclusionAction": { + "description": "What to do with a memory a detector matched. Defaults to `redact`. When matching\ndetectors disagree, `drop` wins.", + "enum": [ + "REDACT", + "DROP" + ], + "type": "string" + }, + "ExtractionCadenceConfig": { + "description": "Cadence configuration for the extraction pipeline.", + "properties": { + "activeIntervalSeconds": { + "description": "Interval in seconds between extraction runs while a session is active.", + "format": "int32", + "maximum": 600, + "minimum": 60, + "type": "integer" + } + }, + "required": [ + "activeIntervalSeconds" + ], + "type": "object" + }, + "ExtractionStrategy": { + "description": "Extraction strategy for promoting short-term memory to long-term memory. Defaults\nto `INSTRUCT`.", + "enum": [ + "INSTRUCT" + ], + "type": "string" + }, + "ExtractorOutput": { + "properties": { + "createdAt": { + "format": "date-time", + "type": "string" + }, + "destinationNamespaceId": { + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "extractorId": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" + }, + "memoryType": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + }, + "name": { + "description": "Display name of any API resource.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "prompt": { + "type": "string" + }, + "revision": { + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "maxLength": 64, + "minLength": 1, + "type": "string" + }, + "source": { + "$ref": "#/components/schemas/ExtractorSource" + }, + "strategy": { + "$ref": "#/components/schemas/ExtractorStrategy" + }, + "updatedAt": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "createdAt", + "enabled", + "extractorId", + "memoryType", + "name", + "prompt", + "revision", + "source", + "strategy", + "updatedAt" + ], + "type": "object" + }, + "ExtractorSource": { + "enum": [ + "DOCUMENTS" + ], + "type": "string" + }, + "ExtractorStrategy": { + "enum": [ + "CUSTOM" + ], + "type": "string" + }, + "FailedDependencyErrorResponseContent": { + "description": "A dependent resource required to process the request is unavailable or unhealthy.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 424, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/FailedDependencyErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "FailedDependencyErrorType": { + "description": "Problem type URI for failed-dependency errors.", + "enum": [ + "/errors/resource-unavailable", + "/errors/database-out-of-memory", + "/errors/invalid-model-credentials", + "/errors/model-quota-exceeded" + ], + "type": "string" + }, + "FieldError": { + "description": "One invalid request member. A body member is named by `pointer`, a path or query parameter by `parameter`; exactly one of the two is present.", + "properties": { + "detail": { + "description": "What is wrong with the member, in fixed words about the rule it broke, never the rejected value.", + "type": "string" + }, + "parameter": { + "description": "Name of the invalid path or query parameter, such as `limit`.", + "type": "string" + }, + "pointer": { + "description": "JSON Pointer (RFC 6901) to the invalid body member, such as `/vectorSpace/dimensions`.", + "type": "string" + } + }, + "required": [ + "detail" + ], + "type": "object" + }, + "ForbiddenErrorResponseContent": { + "description": "The caller is authenticated but not allowed to access the requested resource.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 403, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ForbiddenErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "ForbiddenErrorType": { + "description": "Problem type URI for authorization errors.", + "enum": [ + "/errors/insufficient-permissions" + ], + "type": "string" + }, + "GetExtractorResponseContent": { + "properties": { + "createdAt": { + "format": "date-time", + "type": "string" + }, + "destinationNamespaceId": { + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "extractorId": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" + }, + "memoryType": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + }, + "name": { + "description": "Display name of any API resource.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "prompt": { + "type": "string" + }, + "revision": { + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "maxLength": 64, + "minLength": 1, + "type": "string" + }, + "source": { + "$ref": "#/components/schemas/ExtractorSource" + }, + "strategy": { + "$ref": "#/components/schemas/ExtractorStrategy" + }, + "updatedAt": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "createdAt", + "enabled", + "extractorId", + "memoryType", + "name", + "prompt", + "revision", + "source", + "strategy", + "updatedAt" + ], + "type": "object" + }, + "GetIngestionHooksResponseContent": { + "properties": { + "beforeApply": { + "$ref": "#/components/schemas/OutputHookEndpointOutput" + }, + "beforeInput": { + "$ref": "#/components/schemas/InputHookEndpointOutput" + }, + "enabled": { + "type": "boolean" + }, + "revision": { + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "enabled", + "revision" + ], + "type": "object" + }, + "GetMemoryTypeReferenceDataResponseContent": { + "description": "Static reference data for registering custom memory types.", + "properties": { + "builtinMemoryTypeNames": { + "description": "Reserved built-in memory type names. A custom memory type name must not\ncollide with any of these.", + "items": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + }, + "type": "array" + }, + "systemFields": { + "description": "System record fields present on every memory record, shown read-only for\nreference in registration UIs.", + "items": { + "$ref": "#/components/schemas/SystemMemoryField" + }, + "type": "array" + } + }, + "required": [ + "builtinMemoryTypeNames", + "systemFields" + ], + "type": "object" + }, + "GetMemoryTypeResponseContent": { + "description": "A custom memory type registered on a store: a named category of long-term memory\nwith its structured fields and, optionally, an extraction strategy.", + "properties": { + "description": { + "description": "Human-readable description of what this memory type captures.", + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/CustomExtractionStrategy" + }, + "fields": { + "description": "Structured fields that make up a record of this type. Optional; a type with no\nfields accepts direct writes carrying no structured attributes.", + "items": { + "$ref": "#/components/schemas/CustomField" + }, + "type": "array" + }, + "name": { + "description": "Unique type name within the store. Must not collide with built-in types\n(semantic, episodic, message, session_summary, session_summary_view).", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } + }, + "required": [ + "description", + "name" + ], + "type": "object" + }, + "GetStoreResponseContent": { + "description": "Memory store configuration and status.", + "properties": { + "createdAt": { + "description": "The UTC timestamp when the memory store was created.", + "format": "date-time", + "type": "string" + }, + "database": { + "$ref": "#/components/schemas/StoreDatabase" + }, + "endpoints": { + "description": "Redis Cloud only. API endpoints for accessing the memory store.", + "items": { + "$ref": "#/components/schemas/StoreEndpoint" + }, + "type": "array", + "x-deployment": "cloud" + }, + "extractionCadence": { + "$ref": "#/components/schemas/ExtractionCadenceConfig" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/ExtractionStrategy" + }, + "failure": { + "$ref": "#/components/schemas/StoreFailure" + }, + "longTermMemory": { + "$ref": "#/components/schemas/LongTermMemoryConfigStatus" + }, + "longTermMemoryExclusions": { + "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + }, + "name": { + "description": "Human-readable name of the memory store.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "shortMemory": { + "$ref": "#/components/schemas/ShortMemoryConfigStatus" + }, + "state": { + "$ref": "#/components/schemas/ResourceState" + }, + "storeId": { + "description": "Unique identifier for the memory store.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + }, + "subscriptionId": { + "description": "Redis Cloud only. The memory store's database subscription ID.", + "type": "string", + "x-deployment": "cloud" + }, + "summarization": { + "$ref": "#/components/schemas/SummarizationConfig" + } + }, + "required": [ + "createdAt", + "database", + "extractionStrategy", + "longTermMemory", + "name", + "state", + "storeId" + ], + "type": "object" + }, + "InputHookEndpointOutput": { + "properties": { + "keyId": { + "type": "string" + }, + "paths": { + "items": { + "$ref": "#/components/schemas/InputHookPath" + }, + "maxItems": 10, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "signingKeyConfigured": { + "type": "boolean" + }, + "url": { + "maxLength": 2048, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "keyId", + "paths", + "signingKeyConfigured", + "url" + ], + "type": "object" + }, + "InputHookEndpointWrite": { + "properties": { + "paths": { + "items": { + "$ref": "#/components/schemas/InputHookPath" + }, + "maxItems": 10, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "signingKey": { + "description": "Omit to keep this phase's current key. Required for a new phase.", + "format": "password", + "maxLength": 44, + "minLength": 44, + "type": "string" + }, + "url": { + "maxLength": 2048, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "paths", + "url" + ], + "type": "object" + }, + "InputHookPath": { + "enum": [ + "session.append", + "memory.create", + "memory.update", + "memory.delete", + "memory.move", + "session.summary", + "session.property", + "session.delete", + "session.events.delete", + "document.submit" + ], + "type": "string" + }, + "ListBuiltInDetectorsResponseContent": { + "properties": { + "catalogVersion": { + "description": "The catalog revision these entries came from, for support.", + "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$", + "type": "string" + }, + "items": { + "description": "The selectable detectors, ordered by id.", + "items": { + "$ref": "#/components/schemas/BuiltInDetector" + }, + "type": "array" + } + }, + "required": [ + "catalogVersion", + "items" + ], + "type": "object" + }, + "ListExtractorsResponseContent": { + "properties": { + "items": { + "description": "The store's extractors, ordered by extractor ID.", + "items": { + "$ref": "#/components/schemas/ExtractorOutput" + }, + "type": "array" + }, + "nextCursor": { + "description": "Present when more extractors follow; pass it back as `cursor`.", + "maxLength": 1024, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "items" + ], + "type": "object" + }, + "ListMemoryTypesResponseContent": { + "properties": { + "items": { + "description": "The store's custom memory types, ordered by name.", + "items": { + "$ref": "#/components/schemas/CustomMemoryType" + }, + "type": "array" + }, + "nextCursor": { + "description": "Present when more memory types follow; pass it back as `cursor`.", + "maxLength": 1024, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "items" + ], + "type": "object" + }, + "ListStoresResponseContent": { + "properties": { + "items": { + "description": "The memory stores, ordered by store ID.", + "items": { + "$ref": "#/components/schemas/StoreOutput" + }, + "type": "array" + }, + "nextCursor": { + "description": "Present when more stores follow; pass it back as `cursor`.", + "maxLength": 1024, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "items" + ], + "type": "object" + }, + "LongTermMemoryConfigInput": { + "description": "Long-term memory configuration.\n\nOn Redis Cloud, `llm` and `embedding` select the store's own models and must be\nsupplied together; `classification` is independent. Omit them to use the platform\nmodels. The embedding model cannot be changed after the store is created.", + "properties": { + "classification": { + "$ref": "#/components/schemas/ModelConfigInput" + }, + "embedding": { + "$ref": "#/components/schemas/ModelConfigInput" + }, + "llm": { + "$ref": "#/components/schemas/ModelConfigInput" + }, + "sessionSummaryEnabled": { + "default": false, + "description": "Extract session summaries into long-term memory. Takes effect only when the\ndeployment enables session summary extraction.", + "type": "boolean" + }, + "ttlSeconds": { + "default": 31536000, + "description": "Time-to-live in seconds for long-term memory entries. Defaults to 1 year.", + "format": "int32", + "maximum": 31536000, + "minimum": 1, + "type": "integer" + } + }, + "type": "object" + }, + "LongTermMemoryConfigStatus": { + "description": "Long-term memory configuration. On Redis Cloud, `embedding`, `llm`, and\n`classification` are present only when the store selected its own models.", + "properties": { + "classification": { + "$ref": "#/components/schemas/ModelConfigStatus" + }, + "embedding": { + "$ref": "#/components/schemas/ModelConfigStatus" + }, + "llm": { + "$ref": "#/components/schemas/ModelConfigStatus" + }, + "sessionSummaryEnabled": { + "description": "Whether session summary extraction into long-term memory is enabled for this store.", + "type": "boolean" + }, + "ttlSeconds": { + "description": "Time-to-live in seconds for long-term memory entries.", + "format": "int32", + "maximum": 31536000, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "sessionSummaryEnabled", + "ttlSeconds" + ], + "type": "object" + }, + "LongTermMemoryConfigUpdate": { + "description": "Long-term memory configuration. Omitted fields keep their current value.\n\nOn Redis Cloud:\n- `embedding`: only the credential can be replaced.\n- `llm`: the model can be changed within the same provider, and the credential\n replaced.\n- `classification`: same as `llm`. A store without a classification model may\n select one.\n\nA store created with the platform models cannot switch `embedding` or `llm` to its\nown models.", + "properties": { + "classification": { + "$ref": "#/components/schemas/ModelConfigInput" + }, + "embedding": { + "$ref": "#/components/schemas/ModelConfigInput" + }, + "llm": { + "$ref": "#/components/schemas/ModelConfigInput" + }, + "sessionSummaryEnabled": { + "description": "Extract session summaries into long-term memory. Omit to keep the current value.", + "type": "boolean" + }, + "ttlSeconds": { + "description": "Time-to-live in seconds for long-term memory entries.", + "format": "int32", + "maximum": 31536000, + "minimum": 1, + "type": "integer" + } + }, + "type": "object" + }, + "LongTermMemoryExclusionsConfig": { + "description": "Store-level sensitive-data exclusions policy.", + "properties": { + "builtInDetectors": { + "$ref": "#/components/schemas/BuiltInDetectorsConfig" + }, + "customDetectors": { + "$ref": "#/components/schemas/CustomDetectorsConfig" + }, + "enabled": { + "description": "Master toggle for the exclusions feature.", + "type": "boolean" + }, + "semantic": { + "$ref": "#/components/schemas/SemanticExclusionConfig" + } + }, + "required": [ + "enabled" + ], + "type": "object" + }, + "MatcherKind": { + "description": "The supported matching techniques.", + "enum": [ + "REGEX" + ], + "type": "string" + }, + "MatcherSpec": { + "description": "How a detector matches. Exactly the block named by `kind` must be present.", + "properties": { + "kind": { + "$ref": "#/components/schemas/MatcherKind" + }, + "regex": { + "$ref": "#/components/schemas/RegexSpec" + } + }, + "required": [ + "kind" + ], + "type": "object" + }, + "ModelConfigInput": { + "description": "Redis Cloud only. A model selection.", + "properties": { + "credentials": { + "$ref": "#/components/schemas/ModelCredentialsInput" + }, + "model": { + "description": "The model to use. Required on create. On update, omit it to keep the current\nmodel.", + "type": "string" + }, + "provider": { + "description": "The model provider.", + "type": "string" + } + }, + "type": "object", + "x-deployment": "cloud" + }, + "ModelConfigStatus": { + "description": "Redis Cloud only. The model a store uses.", + "properties": { + "model": { + "description": "The model in use.", + "type": "string" + }, + "provider": { + "description": "The model provider in use.", + "type": "string" + } + }, + "required": [ + "model", + "provider" + ], + "type": "object", + "x-deployment": "cloud" + }, + "ModelCredentialType": { + "description": "How the secret behind a model credential is to be interpreted.", + "enum": [ + "API_KEY" + ], + "type": "string" + }, + "ModelCredentialsInput": { + "description": "Redis Cloud only. A provider credential. Never returned by any operation.", + "properties": { + "apiKey": { + "description": "The provider API key. Required on create. On update, omit it to keep the\ncurrent key.", + "format": "password", + "type": "string" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "type": { + "$ref": "#/components/schemas/ModelCredentialType" + } + }, + "required": [ + "type" + ], + "type": "object", + "x-deployment": "cloud" + }, + "NotFoundErrorResponseContent": { + "description": "The requested resource does not exist.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "status": { + "default": 404, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/NotFoundErrorType" } - } - } - }, - "/v1/stores": { - "get": { - "operationId": "ListStores", - "responses": { - "200": { - "description": "ListStores 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListStoresResponseContent" - } - } - } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "NotFoundErrorType": { + "description": "Problem type URI for not-found errors.", + "enum": [ + "/errors/resource-not-found", + "/errors/gateway-not-found", + "/errors/upstream-not-found" + ], + "type": "string" + }, + "NotImplementedErrorResponseContent": { + "description": "The requested capability is recognized but not implemented.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "status": { + "default": 501, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/NotImplementedErrorType" } - } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" }, - "post": { - "operationId": "CreateStore", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateStoreRequestContent" - } - } + "NotImplementedErrorType": { + "description": "Problem type URI for not-implemented errors.", + "enum": [ + "/errors/not-implemented" + ], + "type": "string" + }, + "OutputHookEndpointOutput": { + "properties": { + "keyId": { + "type": "string" }, - "required": true + "paths": { + "items": { + "$ref": "#/components/schemas/OutputHookPath" + }, + "maxItems": 4, + "minItems": 1, + "type": "array", + "uniqueItems": true + }, + "signingKeyConfigured": { + "type": "boolean" + }, + "url": { + "maxLength": 2048, + "minLength": 1, + "type": "string" + } }, - "responses": { - "201": { - "description": "CreateStore 201 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateStoreResponseContent" - } - } - } + "required": [ + "keyId", + "paths", + "signingKeyConfigured", + "url" + ], + "type": "object" + }, + "OutputHookEndpointWrite": { + "properties": { + "paths": { + "items": { + "$ref": "#/components/schemas/OutputHookPath" + }, + "maxItems": 4, + "minItems": 1, + "type": "array", + "uniqueItems": true }, - "400": { - "description": "BadRequestError 400 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BadRequestErrorResponseContent" - } - } - } + "signingKey": { + "description": "Exactly 32 bytes in canonical padded base64. Never returned by a read.", + "format": "password", + "maxLength": 44, + "minLength": 44, + "type": "string" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "url": { + "maxLength": 2048, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "paths", + "url" + ], + "type": "object" + }, + "OutputHookPath": { + "enum": [ + "document.chunk", + "session.builtin", + "session.custom", + "summary_view.refresh" + ], + "type": "string" + }, + "PreconditionFailedErrorResponseContent": { + "description": "The write named an expected revision (expectedRevision or If-Match) that is no longer current. Read the resource again and retry.", + "properties": { + "currentRevision": { + "description": "The resource's current revision, when the service reports it. Read the resource again before retrying; do not send this value back without reading.", + "type": "string" + }, + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 412, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/PreconditionFailedErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "PreconditionFailedErrorType": { + "description": "Problem type URI for a write whose expected revision is no longer current. A write guarded by an If-Match header on an HTTP entity tag uses a different type; see the Identity Service API.", + "enum": [ + "/errors/revision-conflict" + ], + "type": "string" + }, + "PutIngestionHooksRequestContent": { + "properties": { + "beforeApply": { + "$ref": "#/components/schemas/OutputHookEndpointWrite" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "beforeInput": { + "$ref": "#/components/schemas/InputHookEndpointWrite" }, - "424": { - "description": "FailedDependencyError 424 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" - } - } - } + "enabled": { + "type": "boolean" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } - } - } - } - }, - "/v1/stores/{storeId}": { - "delete": { - "operationId": "DeleteStore", - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "expectedRevision": { + "description": "The `revision` GetIngestionHooks returned: `0` for a store whose hooks were never\nconfigured. A stale value fails with 412 `/errors/revision-conflict`. Each\nsuccessful write gives the configuration a new revision.", + "maxLength": 64, + "minLength": 1, + "type": "string" } + }, + "required": [ + "enabled", + "expectedRevision" ], - "responses": { - "204": { - "description": "DeleteStore 204 response" + "type": "object" + }, + "PutIngestionHooksResponseContent": { + "properties": { + "beforeApply": { + "$ref": "#/components/schemas/OutputHookEndpointOutput" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "beforeInput": { + "$ref": "#/components/schemas/InputHookEndpointOutput" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "enabled": { + "type": "boolean" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "revision": { + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "enabled", + "revision" + ], + "type": "object" + }, + "RedisCloudDatabase": { + "description": "Redis Cloud only. Redis Cloud details of a database.", + "properties": { + "accessCidrs": { + "description": "Database CIDR allow-list items.", + "items": { + "type": "string" + }, + "type": "array" }, - "424": { - "description": "FailedDependencyError 424 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" - } - } - } + "provider": { + "description": "The cloud provider where the database is provisioned.", + "type": "string" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "region": { + "description": "The cloud region where the database is provisioned.", + "type": "string" } - } + }, + "type": "object", + "x-deployment": "cloud" }, - "get": { - "operationId": "GetStore", - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "RegexSpec": { + "description": "A regular expression in RE2 syntax (no lookaround or backreferences). Required\nwhen `kind` is `regex`, and rejected otherwise. Rejected if it does not compile, or\nif it can match empty text.", + "properties": { + "pattern": { + "description": "The pattern, in RE2 syntax.", + "maxLength": 512, + "minLength": 1, + "type": "string" } + }, + "required": [ + "pattern" ], - "responses": { - "200": { - "description": "GetStore 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GetStoreResponseContent" - } - } - } + "type": "object" + }, + "ResourceState": { + "description": "The condition of a provisioned resource, returned as `state`. A resource is usable\nwhen its state is `READY`. A resource reports only the states that apply to it.", + "enum": [ + "PROVISIONING", + "READY", + "UNAVAILABLE", + "FAILED", + "SUSPENDED", + "DELETING" + ], + "type": "string" + }, + "SemanticExclusionConfig": { + "description": "Semantic exclusion configuration.", + "properties": { + "enabled": { + "description": "Whether semantic exclusion is enabled.", + "type": "boolean" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "prompt": { + "description": "Instruction describing what to exclude.", + "type": "string" + } + }, + "required": [ + "enabled" + ], + "type": "object" + }, + "ServiceUnavailableErrorResponseContent": { + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "status": { + "default": 503, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ServiceUnavailableErrorType" } - } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" }, - "patch": { - "operationId": "UpdateStore", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateStoreRequestContent" - } - } + "ServiceUnavailableErrorType": { + "enum": [ + "/errors/service-unavailable", + "/errors/playbook-not-ready", + "/errors/resource-unavailable" + ], + "type": "string" + }, + "ShortMemoryConfigInput": { + "description": "Short-term memory configuration.", + "properties": { + "ttlSeconds": { + "description": "Time-to-live in seconds for short-term memory entries. When omitted, no TTL is\nset on create, and the current value is kept on update.", + "format": "int32", + "maximum": 31536000, + "minimum": 1, + "type": "integer" } }, - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "type": "object" + }, + "ShortMemoryConfigStatus": { + "description": "Short-term memory configuration. Omitted when no TTL is set.", + "properties": { + "ttlSeconds": { + "description": "Time-to-live in seconds for short-term memory entries.", + "format": "int32", + "maximum": 31536000, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "ttlSeconds" + ], + "type": "object" + }, + "StoreDatabase": { + "description": "The database a memory store's data is stored in.", + "properties": { + "databaseId": { + "description": "The database ID.", + "maxLength": 32, + "minLength": 1, + "type": "string" + }, + "name": { + "description": "The database name.", + "type": "string" + }, + "redisCloud": { + "$ref": "#/components/schemas/RedisCloudDatabase" } + }, + "required": [ + "databaseId", + "name" ], - "responses": { - "200": { - "description": "UpdateStore 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateStoreResponseContent" - } - } - } + "type": "object" + }, + "StoreEndpoint": { + "description": "Redis Cloud only. An API endpoint for accessing the memory store.", + "properties": { + "accessible": { + "description": "Whether the endpoint can reach the database, based on its egress IPs and the\ndatabase CIDR allow-list.", + "type": "boolean" }, - "400": { - "description": "BadRequestError 400 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BadRequestErrorResponseContent" - } - } - } + "egressIps": { + "description": "Egress IP addresses of the endpoint.", + "items": { + "type": "string" + }, + "type": "array" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "provider": { + "description": "The endpoint cloud provider.", + "type": "string" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "region": { + "description": "The endpoint cloud region.", + "type": "string" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "url": { + "description": "The URL of the endpoint.", + "type": "string" + } + }, + "required": [ + "accessible", + "provider", + "region", + "url" + ], + "type": "object", + "x-deployment": "cloud" + }, + "StoreFailure": { + "description": "Why the store failed to provision. Present only when the store's `state` is\n`UNAVAILABLE`. Not returned by ListStores.", + "properties": { + "message": { + "description": "What went wrong.", + "type": "string" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "occurredAt": { + "description": "The UTC timestamp when the failure occurred.", + "format": "date-time", + "type": "string" } - } - } - }, - "/v1/stores/{storeId}/extractors": { - "get": { - "operationId": "ListExtractors", - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + }, + "required": [ + "message", + "occurredAt" + ], + "type": "object" + }, + "StoreOutput": { + "description": "Memory store configuration and status.", + "properties": { + "createdAt": { + "description": "The UTC timestamp when the memory store was created.", + "format": "date-time", + "type": "string" + }, + "database": { + "$ref": "#/components/schemas/StoreDatabase" + }, + "endpoints": { + "description": "Redis Cloud only. API endpoints for accessing the memory store.", + "items": { + "$ref": "#/components/schemas/StoreEndpoint" }, - "required": true + "type": "array", + "x-deployment": "cloud" + }, + "extractionCadence": { + "$ref": "#/components/schemas/ExtractionCadenceConfig" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/ExtractionStrategy" + }, + "failure": { + "$ref": "#/components/schemas/StoreFailure" + }, + "longTermMemory": { + "$ref": "#/components/schemas/LongTermMemoryConfigStatus" + }, + "longTermMemoryExclusions": { + "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + }, + "name": { + "description": "Human-readable name of the memory store.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "shortMemory": { + "$ref": "#/components/schemas/ShortMemoryConfigStatus" + }, + "state": { + "$ref": "#/components/schemas/ResourceState" + }, + "storeId": { + "description": "Unique identifier for the memory store.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + }, + "subscriptionId": { + "description": "Redis Cloud only. The memory store's database subscription ID.", + "type": "string", + "x-deployment": "cloud" + }, + "summarization": { + "$ref": "#/components/schemas/SummarizationConfig" } + }, + "required": [ + "createdAt", + "database", + "extractionStrategy", + "longTermMemory", + "name", + "state", + "storeId" ], - "responses": { - "200": { - "description": "ListExtractors 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListExtractorsResponseContent" - } - } - } - }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "type": "object" + }, + "SummarizationConfig": { + "description": "Configuration for session summarization. When enabled, long sessions are\nperiodically condensed into a running summary while retaining the most recent events.", + "properties": { + "enabled": { + "description": "Whether summarization is enabled for this store.", + "type": "boolean" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "eventCount": { + "$ref": "#/components/schemas/SummarizationThresholdConfig" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "triggerStrategy": { + "$ref": "#/components/schemas/SummarizationTriggerStrategy" + } + }, + "required": [ + "enabled" + ], + "type": "object" + }, + "SummarizationThresholdConfig": { + "description": "Configuration for a summarization trigger.", + "properties": { + "retainCount": { + "description": "Number of most recent events to retain after each summarization cycle.", + "format": "int32", + "type": "integer" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "threshold": { + "description": "The threshold value that triggers summarization.", + "format": "int32", + "type": "integer" } - } + }, + "required": [ + "retainCount", + "threshold" + ], + "type": "object" }, - "post": { - "operationId": "CreateExtractor", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateExtractorRequestContent" - } - } + "SummarizationTriggerStrategy": { + "description": "Strategy that determines when summarization is triggered. Defaults to\n`EVENT_COUNT`.", + "enum": [ + "EVENT_COUNT" + ], + "type": "string" + }, + "SystemFieldType": { + "description": "Data type of a system field on every memory record. A value shared with\n`CustomFieldType` means the same type.", + "enum": [ + "STRING", + "STRING_LIST", + "ENUM", + "DATETIME" + ], + "type": "string" + }, + "SystemMemoryField": { + "description": "A built-in field present on every memory record. It cannot be edited or\nremoved when registering a custom type.", + "properties": { + "description": { + "description": "Human-readable description of the field.", + "type": "string" }, - "required": true + "name": { + "description": "Field name as it appears on a memory record.", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/SystemFieldType" + } }, - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "required": [ + "description", + "name", + "type" + ], + "type": "object" + }, + "UnexpectedErrorResponseContent": { + "description": "The service failed with an unexpected internal error.", + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 500, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/UnexpectedErrorType" } + }, + "required": [ + "status", + "title", + "type" ], - "responses": { - "201": { - "description": "CreateExtractor 201 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateExtractorResponseContent" - } - } - } + "type": "object" + }, + "UnexpectedErrorType": { + "description": "Problem type URI for unexpected internal errors.", + "enum": [ + "/errors/unexpected-error", + "/errors/content-integrity-failed" + ], + "type": "string" + }, + "UpdateExtractorRequestContent": { + "properties": { + "destinationNamespaceId": { + "description": "Empty string clears the destination namespace. Omitted leaves it unchanged.", + "type": "string" }, - "400": { - "description": "BadRequestError 400 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BadRequestErrorResponseContent" - } - } - } + "enabled": { + "type": "boolean" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "expectedRevision": { + "description": "The extractor's `revision` as last read.", + "maxLength": 64, + "minLength": 1, + "type": "string" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "name": { + "description": "Display name of any API resource.", + "maxLength": 128, + "minLength": 1, + "type": "string" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "prompt": { + "type": "string" + } + }, + "required": [ + "expectedRevision" + ], + "type": "object" + }, + "UpdateExtractorResponseContent": { + "properties": { + "createdAt": { + "format": "date-time", + "type": "string" }, - "409": { - "description": "ConflictError 409 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConflictErrorResponseContent" - } - } - } + "destinationNamespaceId": { + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "type": "string" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } - } - } - } - }, - "/v1/stores/{storeId}/extractors/{extractorId}": { - "delete": { - "operationId": "RemoveExtractor", - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "enabled": { + "type": "boolean" }, - { - "name": "extractorId", - "in": "path", - "description": "Store-scoped Extractor identifier.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." - }, - "required": true + "extractorId": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" }, - { - "name": "expectedRevision", - "in": "query", - "schema": { - "type": "integer", - "format": "int64" - }, - "required": true - } - ], - "responses": { - "204": { - "description": "RemoveExtractor 204 response" + "memoryType": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "name": { + "description": "Display name of any API resource.", + "maxLength": 128, + "minLength": 1, + "type": "string" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "prompt": { + "type": "string" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "revision": { + "description": "Resource revision. Opaque: each change to a resource's own configuration writes a\nnew value, and a resource never gets a value it had before. Compare for equality\nonly; its format is the service's, so only its length is constrained. Returned as\n`revision`; sent back as `expectedRevision` to make a write conditional. Omitting\n`expectedRevision` makes the write unconditional.", + "maxLength": 64, + "minLength": 1, + "type": "string" }, - "409": { - "description": "ConflictError 409 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConflictErrorResponseContent" - } - } - } + "source": { + "$ref": "#/components/schemas/ExtractorSource" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "strategy": { + "$ref": "#/components/schemas/ExtractorStrategy" + }, + "updatedAt": { + "format": "date-time", + "type": "string" } - } + }, + "required": [ + "createdAt", + "enabled", + "extractorId", + "memoryType", + "name", + "prompt", + "revision", + "source", + "strategy", + "updatedAt" + ], + "type": "object" }, - "get": { - "operationId": "GetExtractor", - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "UpdateMemoryTypeRequestContent": { + "properties": { + "extractionStrategy": { + "$ref": "#/components/schemas/CustomExtractionStrategyUpdate" + } + }, + "required": [ + "extractionStrategy" + ], + "type": "object" + }, + "UpdateMemoryTypeResponseContent": { + "description": "A custom memory type registered on a store: a named category of long-term memory\nwith its structured fields and, optionally, an extraction strategy.", + "properties": { + "description": { + "description": "Human-readable description of what this memory type captures.", + "maxLength": 200, + "minLength": 1, + "type": "string" }, - { - "name": "extractorId", - "in": "path", - "description": "Store-scoped Extractor identifier.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." + "extractionStrategy": { + "$ref": "#/components/schemas/CustomExtractionStrategy" + }, + "fields": { + "description": "Structured fields that make up a record of this type. Optional; a type with no\nfields accepts direct writes carrying no structured attributes.", + "items": { + "$ref": "#/components/schemas/CustomField" }, - "required": true + "type": "array" + }, + "name": { + "description": "Unique type name within the store. Must not collide with built-in types\n(semantic, episodic, message, session_summary, session_summary_view).", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" } - ], - "responses": { - "200": { - "description": "GetExtractor 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GetExtractorResponseContent" - } - } - } + }, + "required": [ + "description", + "name" + ], + "type": "object" + }, + "UpdateStoreRequestContent": { + "properties": { + "extractionCadence": { + "$ref": "#/components/schemas/ExtractionCadenceConfig" }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } - } + "longTermMemory": { + "$ref": "#/components/schemas/LongTermMemoryConfigUpdate" }, - "403": { - "description": "ForbiddenError 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" - } - } - } + "longTermMemoryExclusions": { + "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + "name": { + "description": "Updated name for the memory store.", + "maxLength": 128, + "minLength": 1, + "type": "string" }, - "500": { - "description": "UnexpectedError 500 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" - } - } - } + "shortMemory": { + "$ref": "#/components/schemas/ShortMemoryConfigInput" + }, + "summarization": { + "$ref": "#/components/schemas/SummarizationConfig" } - } + }, + "type": "object" }, - "patch": { - "operationId": "UpdateExtractor", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateExtractorRequestContent" - } - } + "UpdateStoreResponseContent": { + "description": "Memory store configuration and status.", + "properties": { + "createdAt": { + "description": "The UTC timestamp when the memory store was created.", + "format": "date-time", + "type": "string" }, - "required": true - }, - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true + "database": { + "$ref": "#/components/schemas/StoreDatabase" }, - { - "name": "extractorId", - "in": "path", - "description": "Store-scoped Extractor identifier.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." + "endpoints": { + "description": "Redis Cloud only. API endpoints for accessing the memory store.", + "items": { + "$ref": "#/components/schemas/StoreEndpoint" }, - "required": true + "type": "array", + "x-deployment": "cloud" + }, + "extractionCadence": { + "$ref": "#/components/schemas/ExtractionCadenceConfig" + }, + "extractionStrategy": { + "$ref": "#/components/schemas/ExtractionStrategy" + }, + "failure": { + "$ref": "#/components/schemas/StoreFailure" + }, + "longTermMemory": { + "$ref": "#/components/schemas/LongTermMemoryConfigStatus" + }, + "longTermMemoryExclusions": { + "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + }, + "name": { + "description": "Human-readable name of the memory store.", + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "shortMemory": { + "$ref": "#/components/schemas/ShortMemoryConfigStatus" + }, + "state": { + "$ref": "#/components/schemas/ResourceState" + }, + "storeId": { + "description": "Unique identifier for the memory store.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + }, + "subscriptionId": { + "description": "Redis Cloud only. The memory store's database subscription ID.", + "type": "string", + "x-deployment": "cloud" + }, + "summarization": { + "$ref": "#/components/schemas/SummarizationConfig" } + }, + "required": [ + "createdAt", + "database", + "extractionStrategy", + "longTermMemory", + "name", + "state", + "storeId" ], + "type": "object" + } + }, + "securitySchemes": { + "smithy.api.httpBearerAuth": { + "description": "HTTP Bearer authentication", + "scheme": "Bearer", + "type": "http" + } + } + }, + "info": { + "description": "Admin API for the Redis Agent Memory control plane, version 2.\n\nFields marked `x-deployment: cloud` are available on Redis Cloud only. They are always optional,\nand on-prem deployments never return them.\n", + "title": "Redis Agent Memory Control Plane API", + "version": "2.0.0" + }, + "openapi": "3.0.2", + "paths": { + "/iris/v1/agent-memory/detectors": { + "get": { + "description": "List the built-in sensitive-data detectors a store can select in its\n`longTermMemoryExclusions.builtInDetectors` configuration. Selecting an id this\nendpoint does not list is rejected.", + "operationId": "ListBuiltInDetectors", "responses": { "200": { - "description": "UpdateExtractor 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateExtractorResponseContent" - } - } - } - }, - "400": { - "description": "BadRequestError 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BadRequestErrorResponseContent" + "$ref": "#/components/schemas/ListBuiltInDetectorsResponseContent" } } - } + }, + "description": "ListBuiltInDetectors 200 response" }, "401": { - "description": "AuthenticationError 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorResponseContent" } } - } + }, + "description": "AuthenticationError 401 response" }, "403": { - "description": "ForbiddenError 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseContent" } } - } - }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + }, + "description": "ForbiddenError 403 response" }, - "409": { - "description": "ConflictError 409 response", + "500": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConflictErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } - } + }, + "description": "UnexpectedError 500 response" }, - "500": { - "description": "UnexpectedError 500 response", + "503": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } - } + }, + "description": "ServiceUnavailableError 503 response" } - } + }, + "tags": [ + "detectors" + ] } }, - "/v1/stores/{storeId}/ingestion-hooks": { + "/iris/v1/agent-memory/memory-types/reference": { "get": { - "operationId": "GetIngestionHooks", - "parameters": [ - { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", - "schema": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true - } - ], + "description": "Get reference data for registering custom memory types.\n\nReturns the reserved built-in memory type names (which a custom memory type\nname must not collide with) and the system record fields present on every\nmemory record, for display in memory-type registration UIs. This is static\nreference data and is not scoped to any store.", + "operationId": "GetMemoryTypeReferenceData", "responses": { "200": { - "description": "GetIngestionHooks 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetIngestionHooksResponseContent" + "$ref": "#/components/schemas/GetMemoryTypeReferenceDataResponseContent" } } - } + }, + "description": "GetMemoryTypeReferenceData 200 response" }, "401": { - "description": "AuthenticationError 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorResponseContent" } } - } + }, + "description": "AuthenticationError 401 response" }, "403": { - "description": "ForbiddenError 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponseContent" } } - } - }, - "404": { - "description": "NotFoundError 404 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" - } - } - } + }, + "description": "ForbiddenError 403 response" }, - "409": { - "description": "ConflictError 409 response", + "500": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConflictErrorResponseContent" + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } - } + }, + "description": "UnexpectedError 500 response" }, - "500": { - "description": "UnexpectedError 500 response", + "503": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" } } - } + }, + "description": "ServiceUnavailableError 503 response" } - } - }, - "put": { - "operationId": "PutIngestionHooks", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PutIngestionHooksRequestContent" - } - } - }, - "required": true }, + "tags": [ + "stores" + ] + } + }, + "/iris/v1/agent-memory/stores": { + "get": { + "description": "List all memory stores.", + "operationId": "ListStores", "parameters": [ { - "name": "storeId", - "in": "path", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes.", + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", "schema": { - "type": "string", + "description": "The project. Not supported yet; omit it.", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "required": true - } - ], - "responses": { - "200": { - "description": "PutIngestionHooks 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PutIngestionHooksResponseContent" - } - } - } - }, - "400": { - "description": "BadRequestError 400 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BadRequestErrorResponseContent" - } - } + "type": "string" } }, - "401": { - "description": "AuthenticationError 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationErrorResponseContent" - } - } + { + "description": "Maximum number of stores to return. Defaults to 50.", + "in": "query", + "name": "limit", + "schema": { + "default": 50, + "description": "Maximum number of stores to return. Defaults to 50.", + "format": "int32", + "maximum": 200, + "minimum": 1, + "type": "integer" } }, - "403": { - "description": "ForbiddenError 403 response", + { + "description": "Opaque position from a previous page's `nextCursor`.", + "in": "query", + "name": "cursor", + "schema": { + "description": "Opaque position from a previous page's `nextCursor`.", + "maxLength": 1024, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + "$ref": "#/components/schemas/ListStoresResponseContent" } } - } + }, + "description": "ListStores 200 response" }, - "404": { - "description": "NotFoundError 404 response", + "400": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NotFoundErrorResponseContent" + "$ref": "#/components/schemas/BadRequestErrorResponseContent" } } - } + }, + "description": "BadRequestError 400 response" }, - "409": { - "description": "ConflictError 409 response", + "401": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConflictErrorResponseContent" + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" } } - } + }, + "description": "AuthenticationError 401 response" }, - "424": { - "description": "FailedDependencyError 424 response", + "403": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" } } - } + }, + "description": "ForbiddenError 403 response" }, "500": { - "description": "UnexpectedError 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponseContent" } } - } - } - } - } - } - }, - "components": { - "schemas": { - "AuthenticationErrorResponseContent": { - "type": "object", - "description": "Authentication credentials are missing, malformed, or invalid.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 401, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/AuthenticationErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "AuthenticationErrorType": { - "type": "string", - "description": "Problem type URI for authentication errors.", - "enum": [ - "/errors/authentication-failed" - ] - }, - "BadRequestErrorResponseContent": { - "type": "object", - "description": "Request validation or input decoding failed.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 400, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/BadRequestErrorType" - }, - "fields": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FieldError" }, - "description": "Optional field-level validation errors." - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "BadRequestErrorType": { - "type": "string", - "description": "Problem type URI for bad request errors.", - "enum": [ - "/errors/invalid-data" - ] - }, - "BuiltInDetectorItem": { - "type": "object", - "description": "One selectable built-in detector. Carries no enabled flag: the catalog says what\nmay be selected, and the store's own configuration says what is active.", - "properties": { - "id": { - "type": "string", - "description": "The stable detector identifier, as accepted in a store's exclusions\nconfiguration. Kebab-case, with a jurisdiction prefix where the detector is\njurisdiction-specific." - }, - "name": { - "type": "string", - "description": "Human-readable detector name, for display." - }, - "description": { - "type": "string", - "description": "What the detector matches, and what it deliberately does not \u2014 the catalog is\nprecision-first, so an operator choosing between detectors needs the\nlimitation as much as the capability." - } - }, - "required": [ - "description", - "id", - "name" - ] - }, - "BuiltInDetectorsConfig": { - "type": "object", - "description": "Selection of platform built-in detectors for a store.", - "properties": { - "enabled": { - "type": "boolean" - }, - "detectors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DetectorSelection" - } - } - }, - "required": [ - "enabled" - ] - }, - "ConflictErrorResponseContent": { - "type": "object", - "description": "The request conflicts with the current state of the resource.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." - }, - "status": { - "type": "integer", - "default": 409, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" - }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." - }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." - }, - "type": { - "$ref": "#/components/schemas/ConflictErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "ConflictErrorType": { - "type": "string", - "description": "Problem type URI for conflict errors.", - "enum": [ - "/errors/conflict" - ] - }, - "CreateExtractorRequestContent": { - "type": "object", - "properties": { - "name": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Customer-facing Extractor display name." - }, - "source": { - "$ref": "#/components/schemas/ExtractorSource" - }, - "strategy": { - "$ref": "#/components/schemas/ExtractorStrategy" - }, - "memoryType": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Name of a custom memory type or field (1-64 chars). Must start with a letter,\nfollowed by letters, digits, underscores, or dashes." - }, - "prompt": { - "type": "string" - }, - "destinationNamespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "enabled": { - "type": "boolean" - } - }, - "required": [ - "memoryType", - "name", - "prompt", - "source", - "strategy" - ] - }, - "CreateExtractorResponseContent": { - "type": "object", - "properties": { - "id": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." - }, - "revision": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Customer-facing Extractor display name." - }, - "source": { - "$ref": "#/components/schemas/ExtractorSource" - }, - "strategy": { - "$ref": "#/components/schemas/ExtractorStrategy" - }, - "memoryType": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Name of a custom memory type or field (1-64 chars). Must start with a letter,\nfollowed by letters, digits, underscores, or dashes." - }, - "prompt": { - "type": "string" - }, - "destinationNamespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "enabled": { - "type": "boolean" + "description": "UnexpectedError 500 response" }, - "createdAt": { - "type": "string", - "format": "date-time" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" }, - "updatedAt": { - "type": "string", - "format": "date-time" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "createdAt", - "enabled", - "id", - "memoryType", - "name", - "prompt", - "revision", - "source", - "strategy", - "updatedAt" + "tags": [ + "stores" ] }, - "CreateStoreRequestContent": { - "type": "object", - "properties": { - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[A-Za-z0-9._-]+$", - "description": "Operator-supplied store name." + "post": { + "description": "Create a new memory store.", + "operationId": "CreateStore", + "parameters": [ + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStoreRequestContent" + } + } }, - "shortMemory": { - "$ref": "#/components/schemas/ShortMemoryConfig" + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStoreResponseContent" + } + } + }, + "description": "CreateStore 201 response" }, - "longTermMemory": { - "$ref": "#/components/schemas/LongTermMemoryConfig" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "extractionStrategy": { - "$ref": "#/components/schemas/ExtractionStrategy" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "summarization": { - "$ref": "#/components/schemas/SummarizationConfig" + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "longTermMemoryExclusions": { - "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" }, - "customMemoryTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomMemoryType" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } }, - "description": "Custom memory types to register on the store. Optional; when omitted the\nstore uses only built-in memory types." + "description": "UnexpectedError 500 response" }, - "extractionCadence": { - "$ref": "#/components/schemas/ExtractionCadenceConfig" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "name" + "tags": [ + "stores" ] - }, - "CreateStoreResponseContent": { - "type": "object", - "properties": { - "storeId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + } + }, + "/iris/v1/agent-memory/stores/{storeId}": { + "delete": { + "description": "Delete a memory store.", + "operationId": "DeleteStore", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } + }, + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + }, + { + "description": "Whether to delete the store's short-term memory sessions together with the\nstore. Long-term memories are not deleted.", + "in": "query", + "name": "flush", + "schema": { + "default": true, + "description": "Whether to delete the store's short-term memory sessions together with the\nstore. Long-term memories are not deleted.", + "type": "boolean" + } } - }, - "required": [ - "storeId" - ] - }, - "CustomDetector": { - "type": "object", - "properties": { - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Identifies the detector wherever a match of it is reported." + ], + "responses": { + "204": { + "description": "DeleteStore 204 response" }, - "enabled": { - "type": "boolean" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "action": { - "$ref": "#/components/schemas/ExclusionAction" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "matcher": { - "$ref": "#/components/schemas/MatcherSpec" - } - }, - "required": [ - "enabled", - "matcher", - "name" - ] - }, - "CustomDetectorsConfig": { - "type": "object", - "description": "Customer-authored detectors for a store, stored inline. Evaluated together with\nthe built-in group as one flat set.", - "properties": { - "enabled": { - "type": "boolean" + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" + }, + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" + }, + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" }, - "detectors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomDetector" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } }, - "description": "At most 32. Names must be unique within the store and must not be a built-in\ndetector id, which a match would otherwise be indistinguishable from." + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "enabled" + "tags": [ + "stores" ] }, - "CustomExtractionStrategy": { - "type": "object", - "description": "Extraction strategy for a custom memory type.", - "properties": { - "prompt": { - "type": "string", - "description": "Prompt used to extract memories of this type from session events." + "get": { + "description": "Get a memory store by ID. Returns the full configuration and status of the store.", + "operationId": "GetStore", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "enabled": { - "type": "boolean", - "description": "Whether the strategy is active. Defaults to true when omitted." + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } } - }, - "required": [ - "prompt" - ] - }, - "CustomField": { - "type": "object", - "description": "A structured field within a custom memory type.", - "properties": { - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Field name. Letters, digits, underscores, and dashes; must start with a letter." + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetStoreResponseContent" + } + } + }, + "description": "GetStore 200 response" }, - "description": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Human-readable description of the field (1-200 chars)." + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "type": { - "$ref": "#/components/schemas/CustomFieldType" - } - }, - "required": [ - "description", - "name", - "type" - ] - }, - "CustomFieldType": { - "type": "string", - "description": "Supported custom field data types. Mirrors the Context Engine\nFieldDescription.type vocabulary exactly.", - "enum": [ - "str", - "int", - "float", - "bool", - "list[str]", - "list[float]", - "object" - ] - }, - "CustomMemoryType": { - "type": "object", - "description": "A custom memory type registered on a store: a named category of long-term\nmemory with its structured fields and, optionally, an extraction strategy.", - "properties": { - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Unique type name within the store. Must not collide with built-in memory types." + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "description": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Human-readable description of what this memory type captures (1-200 chars)." + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "fields": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomField" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } }, - "description": "Structured fields that make up a record of this type. Optional; a type\nwith no fields accepts direct writes carrying no structured attributes." + "description": "NotFoundError 404 response" }, - "extractionStrategy": { - "$ref": "#/components/schemas/CustomExtractionStrategy" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" + }, + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "description", - "name" + "tags": [ + "stores" ] }, - "DetectorSelection": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "enabled": { - "type": "boolean" + "patch": { + "description": "Update a memory store configuration. Only the specified fields are updated.\nReturns the updated store.", + "operationId": "UpdateStore", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "action": { - "$ref": "#/components/schemas/ExclusionAction" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateStoreRequestContent" + } + } } }, - "required": [ - "enabled", - "id" - ] - }, - "ExclusionAction": { - "type": "string", - "enum": [ - "redact", - "drop" - ] - }, - "ExtractionCadenceConfig": { - "type": "object", - "description": "Cadence configuration for the extraction pipeline.", - "properties": { - "activeIntervalSeconds": { - "type": "integer", - "maximum": 600, - "minimum": 60, - "description": "Interval in seconds between extraction runs while a session is active (60-600).", - "format": "int32" + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateStoreResponseContent" + } + } + }, + "description": "UpdateStore 200 response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" + }, + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" + }, + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "activeIntervalSeconds" - ] - }, - "ExtractionStrategy": { - "type": "string", - "enum": [ - "instruct" + "tags": [ + "stores" ] - }, - "ExtractorOutput": { - "type": "object", - "properties": { - "id": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." + } + }, + "/iris/v1/agent-memory/stores/{storeId}/extractors": { + "get": { + "description": "List a memory store's extractors.", + "operationId": "ListExtractors", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "revision": { - "type": "integer", - "format": "int64" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } }, - "name": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Customer-facing Extractor display name." + { + "description": "Maximum number of extractors to return. Defaults to 50.", + "in": "query", + "name": "limit", + "schema": { + "default": 50, + "description": "Maximum number of extractors to return. Defaults to 50.", + "format": "int32", + "maximum": 200, + "minimum": 1, + "type": "integer" + } }, - "source": { - "$ref": "#/components/schemas/ExtractorSource" + { + "description": "Opaque position from a previous page's `nextCursor`.", + "in": "query", + "name": "cursor", + "schema": { + "description": "Opaque position from a previous page's `nextCursor`.", + "maxLength": 1024, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListExtractorsResponseContent" + } + } + }, + "description": "ListExtractors 200 response" }, - "strategy": { - "$ref": "#/components/schemas/ExtractorStrategy" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "memoryType": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Name of a custom memory type or field (1-64 chars). Must start with a letter,\nfollowed by letters, digits, underscores, or dashes." + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "prompt": { - "type": "string" + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "destinationNamespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "enabled": { - "type": "boolean" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "createdAt": { - "type": "string", - "format": "date-time" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" }, - "updatedAt": { - "type": "string", - "format": "date-time" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "createdAt", - "enabled", - "id", - "memoryType", - "name", - "prompt", - "revision", - "source", - "strategy", - "updatedAt" - ] - }, - "ExtractorSource": { - "type": "string", - "enum": [ - "documents" - ] - }, - "ExtractorStrategy": { - "type": "string", - "enum": [ - "custom" + "tags": [ + "extractors" ] }, - "FailedDependencyErrorResponseContent": { - "type": "object", - "description": "A dependent resource required to process the request is unavailable or unhealthy.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + "post": { + "description": "Create an extractor on a memory store. Returns the created extractor at revision 1.", + "operationId": "CreateExtractor", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "status": { - "type": "integer", - "default": 424, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateExtractorRequestContent" + } + } }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateExtractorResponseContent" + } + } + }, + "description": "CreateExtractor 201 response" }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "type": { - "$ref": "#/components/schemas/FailedDependencyErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "FailedDependencyErrorType": { - "type": "string", - "description": "Problem type URI for failed-dependency errors.", - "enum": [ - "/errors/resource-unavailable", - "/errors/database-out-of-memory" - ] - }, - "FieldError": { - "type": "object", - "description": "Validation error details for a single request field.", - "properties": { - "field": { - "type": "string", - "description": "Name of the invalid request field." + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "rule": { - "type": "string", - "description": "Validation rule that was violated." + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "message": { - "type": "string", - "description": "Human-readable validation error message." - } - }, - "required": [ - "field", - "message", - "rule" - ] - }, - "ForbiddenErrorResponseContent": { - "type": "object", - "description": "The caller is authenticated but not allowed to access the requested resource.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" }, - "status": { - "type": "integer", - "default": 403, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" }, - "type": { - "$ref": "#/components/schemas/ForbiddenErrorType" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "status", - "title", - "type" - ] - }, - "ForbiddenErrorType": { - "type": "string", - "description": "Problem type URI for authorization errors.", - "enum": [ - "/errors/insufficient-permissions" + "tags": [ + "extractors" ] - }, - "GetExtractorResponseContent": { - "type": "object", - "properties": { - "id": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." - }, - "revision": { - "type": "integer", - "format": "int64" + } + }, + "/iris/v1/agent-memory/stores/{storeId}/extractors/{extractorId}": { + "delete": { + "description": "Remove an extractor. `expectedRevision` must match the extractor's current\nrevision; otherwise the request fails with 412 `/errors/revision-conflict`.", + "operationId": "RemoveExtractor", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "name": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Customer-facing Extractor display name." + { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "extractorId", + "required": true, + "schema": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" + } }, - "source": { - "$ref": "#/components/schemas/ExtractorSource" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } }, - "strategy": { - "$ref": "#/components/schemas/ExtractorStrategy" + { + "description": "The extractor's `revision` as last read.", + "in": "query", + "name": "expectedRevision", + "required": true, + "schema": { + "description": "The extractor's `revision` as last read.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "RemoveExtractor 204 response" }, - "memoryType": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Name of a custom memory type or field (1-64 chars). Must start with a letter,\nfollowed by letters, digits, underscores, or dashes." + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "prompt": { - "type": "string" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "destinationNamespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "enabled": { - "type": "boolean" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "createdAt": { - "type": "string", - "format": "date-time" + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" }, - "updatedAt": { - "type": "string", - "format": "date-time" - } - }, - "required": [ - "createdAt", - "enabled", - "id", - "memoryType", - "name", - "prompt", - "revision", - "source", - "strategy", - "updatedAt" - ] - }, - "GetIngestionHooksResponseContent": { - "type": "object", - "properties": { - "revision": { - "type": "integer", - "format": "int64" + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + }, + "description": "PreconditionFailedError 412 response" }, - "enabled": { - "type": "boolean" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "beforeInput": { - "$ref": "#/components/schemas/InputHookEndpointOutput" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" }, - "beforeApply": { - "$ref": "#/components/schemas/OutputHookEndpointOutput" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "enabled", - "revision" + "tags": [ + "extractors" ] }, - "GetStoreResponseContent": { - "type": "object", - "properties": { - "storeId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + "get": { + "description": "Get an extractor.", + "operationId": "GetExtractor", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[A-Za-z0-9._-]+$", - "description": "Operator-supplied store name." + { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "extractorId", + "required": true, + "schema": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" + } }, - "status": { - "$ref": "#/components/schemas/StoreStatus" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetExtractorResponseContent" + } + } + }, + "description": "GetExtractor 200 response" }, - "shortMemory": { - "$ref": "#/components/schemas/ShortMemoryConfig" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "longTermMemory": { - "$ref": "#/components/schemas/LongTermMemoryConfig" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "extractionStrategy": { - "$ref": "#/components/schemas/ExtractionStrategy" + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "summarization": { - "$ref": "#/components/schemas/SummarizationConfig" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "longTermMemoryExclusions": { - "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "customMemoryTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomMemoryType" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } }, - "description": "Custom memory types registered on the store." + "description": "NotImplementedError 501 response" }, - "extractionCadence": { - "$ref": "#/components/schemas/ExtractionCadenceConfig" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "name", - "status", - "storeId" + "tags": [ + "extractors" ] }, - "InputHookEndpointOutput": { - "type": "object", - "properties": { - "url": { - "type": "string", - "maxLength": 2048, - "minLength": 1 - }, - "paths": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InputHookPath" - }, - "maxItems": 10, - "minItems": 1, - "uniqueItems": true + "patch": { + "description": "Update an extractor. `expectedRevision` must match the extractor's current\nrevision; otherwise the request fails with 412 `/errors/revision-conflict`.", + "operationId": "UpdateExtractor", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "keyId": { - "type": "string" + { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "extractorId", + "required": true, + "schema": { + "description": "Server-generated extractor identifier: ex_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^ex_[0-9a-f]{32}$", + "type": "string" + } }, - "signingKeyConfigured": { - "type": "boolean" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateExtractorRequestContent" + } + } + }, + "required": true }, - "required": [ - "keyId", - "paths", - "signingKeyConfigured", - "url" - ] - }, - "InputHookEndpointWrite": { - "type": "object", - "properties": { - "url": { - "type": "string", - "maxLength": 2048, - "minLength": 1 + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateExtractorResponseContent" + } + } + }, + "description": "UpdateExtractor 200 response" }, - "paths": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InputHookPath" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } }, - "maxItems": 10, - "minItems": 1, - "uniqueItems": true + "description": "BadRequestError 400 response" }, - "signingKey": { - "type": "string", - "maxLength": 44, - "minLength": 44, - "description": "Omit to keep this phase's current key. Required for a new phase.", - "format": "password" - } - }, - "required": [ - "paths", - "url" - ] - }, - "InputHookPath": { - "type": "string", - "enum": [ - "session.append", - "memory.create", - "memory.update", - "memory.delete", - "memory.move", - "session.summary", - "session.property", - "session.delete", - "session.events.delete", - "document.submit" - ] - }, - "ListBuiltInDetectorsResponseContent": { - "type": "object", - "properties": { - "catalogVersion": { - "type": "string", - "description": "The catalog revision these entries came from, for support and for\ncorrelating a result with the detector generation that produced it. Not a\ncompatibility contract: the ids are." + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + }, + "description": "PreconditionFailedError 412 response" }, - "detectors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/BuiltInDetectorItem" + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } }, - "description": "The selectable detectors, ordered by id. Never empty." - } - }, - "required": [ - "catalogVersion", - "detectors" - ] - }, - "ListExtractorsResponseContent": { - "type": "object", - "properties": { - "extractors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExtractorOutput" - } - } - }, - "required": [ - "extractors" - ] - }, - "ListStoresResponseContent": { - "type": "object", - "properties": { - "stores": { - "type": "array", - "items": { - "$ref": "#/components/schemas/StoreOutput" - } - } - }, - "required": [ - "stores" - ] - }, - "LongTermMemoryConfig": { - "type": "object", - "properties": { - "ttlSeconds": { - "type": "integer", - "format": "int32" - } - } - }, - "LongTermMemoryExclusionsConfig": { - "type": "object", - "description": "Store-level sensitive-data exclusions policy.", - "properties": { - "enabled": { - "type": "boolean" + "description": "FailedDependencyError 424 response" }, - "semantic": { - "$ref": "#/components/schemas/SemanticExclusionConfig" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "builtInDetectors": { - "$ref": "#/components/schemas/BuiltInDetectorsConfig" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" }, - "customDetectors": { - "$ref": "#/components/schemas/CustomDetectorsConfig" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "enabled" - ] - }, - "MatcherKind": { - "type": "string", - "enum": [ - "regex" + "tags": [ + "extractors" ] - }, - "MatcherSpec": { - "type": "object", - "description": "How a detector matches. Exactly the block naming the declared kind must be\npresent; further kinds are additive.", - "properties": { - "kind": { - "$ref": "#/components/schemas/MatcherKind" + } + }, + "/iris/v1/agent-memory/stores/{storeId}/ingestion-hooks": { + "get": { + "operationId": "GetIngestionHooks", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "regex": { - "$ref": "#/components/schemas/RegexSpec" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } } - }, - "required": [ - "kind" - ] - }, - "MemoryTypeStrategyUpdate": { - "type": "object", - "description": "A strategy edit targeting one existing custom memory type. Omitted optional\nfields are left unchanged.", - "properties": { - "typeName": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Name of the existing custom memory type whose strategy is being edited." + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetIngestionHooksResponseContent" + } + } + }, + "description": "GetIngestionHooks 200 response" }, - "prompt": { - "type": "string", - "description": "Replacement extraction prompt. Omit to leave the prompt unchanged." + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "enabled": { - "type": "boolean", - "description": "Replacement enabled flag. Omit to leave the flag unchanged." - } - }, - "required": [ - "typeName" - ] - }, - "NotFoundErrorResponseContent": { - "type": "object", - "description": "The requested resource does not exist.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "status": { - "type": "integer", - "default": 404, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "type": { - "$ref": "#/components/schemas/NotFoundErrorType" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "NotFoundErrorType": { - "type": "string", - "description": "Problem type URI for not-found errors.", - "enum": [ - "/errors/resource-not-found" - ] + } }, - "OutputHookEndpointOutput": { - "type": "object", - "properties": { - "url": { - "type": "string", - "maxLength": 2048, - "minLength": 1 - }, - "paths": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OutputHookPath" - }, - "maxItems": 4, - "minItems": 1, - "uniqueItems": true + "put": { + "operationId": "PutIngestionHooks", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "keyId": { - "type": "string" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PutIngestionHooksRequestContent" + } + } }, - "signingKeyConfigured": { - "type": "boolean" - } + "required": true }, - "required": [ - "keyId", - "paths", - "signingKeyConfigured", - "url" - ] - }, - "OutputHookEndpointWrite": { - "type": "object", - "properties": { - "url": { - "type": "string", - "maxLength": 2048, - "minLength": 1 + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PutIngestionHooksResponseContent" + } + } + }, + "description": "PutIngestionHooks 200 response" }, - "paths": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OutputHookPath" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } }, - "maxItems": 4, - "minItems": 1, - "uniqueItems": true + "description": "BadRequestError 400 response" }, - "signingKey": { - "type": "string", - "maxLength": 44, - "minLength": 44, - "description": "Exactly 32 bytes in canonical padded base64. Never returned by a read.", - "format": "password" - } - }, - "required": [ - "paths", - "url" - ] - }, - "OutputHookPath": { - "type": "string", - "enum": [ - "document.chunk", - "session.builtin", - "session.custom", - "summary_view.refresh" - ] - }, - "PutIngestionHooksRequestContent": { - "type": "object", - "properties": { - "expectedRevision": { - "type": "integer", - "minimum": 0, - "description": "Zero configures a store for the first time. Each successful write advances revision.", - "format": "int64" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "enabled": { - "type": "boolean" + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "beforeInput": { - "$ref": "#/components/schemas/InputHookEndpointWrite" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "beforeApply": { - "$ref": "#/components/schemas/OutputHookEndpointWrite" - } - }, - "required": [ - "enabled", - "expectedRevision" - ] - }, - "PutIngestionHooksResponseContent": { - "type": "object", - "properties": { - "revision": { - "type": "integer", - "format": "int64" + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" }, - "enabled": { - "type": "boolean" + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + }, + "description": "PreconditionFailedError 412 response" }, - "beforeInput": { - "$ref": "#/components/schemas/InputHookEndpointOutput" + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" }, - "beforeApply": { - "$ref": "#/components/schemas/OutputHookEndpointOutput" - } - }, - "required": [ - "enabled", - "revision" - ] - }, - "RegexSpec": { - "type": "object", - "description": "A regular expression, evaluated by RE2 \u2014 linear-time, and therefore without\nlookaround. Rejected on write if it does not compile, or if it can match without\nconsuming text.", - "properties": { - "pattern": { - "type": "string", - "maxLength": 512, - "minLength": 1 - } - }, - "required": [ - "pattern" - ] - }, - "SemanticExclusionConfig": { - "type": "object", - "description": "Semantic exclusion configuration for advisory LLM-mediated filtering.", - "properties": { - "enabled": { - "type": "boolean" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "prompt": { - "type": "string" - } - }, - "required": [ - "enabled" - ] - }, - "ShortMemoryConfig": { - "type": "object", - "properties": { - "ttlSeconds": { - "type": "integer", - "format": "int32" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" } } - }, - "StoreOutput": { - "type": "object", - "properties": { - "storeId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + } + }, + "/iris/v1/agent-memory/stores/{storeId}/memory-types": { + "get": { + "description": "List a store's custom memory types.", + "operationId": "ListMemoryTypes", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[A-Za-z0-9._-]+$", - "description": "Operator-supplied store name." + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } }, - "status": { - "$ref": "#/components/schemas/StoreStatus" + { + "description": "Maximum number of memory types to return. Defaults to 50.", + "in": "query", + "name": "limit", + "schema": { + "default": 50, + "description": "Maximum number of memory types to return. Defaults to 50.", + "format": "int32", + "maximum": 200, + "minimum": 1, + "type": "integer" + } }, - "shortMemory": { - "$ref": "#/components/schemas/ShortMemoryConfig" + { + "description": "Opaque position from a previous page's `nextCursor`.", + "in": "query", + "name": "cursor", + "schema": { + "description": "Opaque position from a previous page's `nextCursor`.", + "maxLength": 1024, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListMemoryTypesResponseContent" + } + } + }, + "description": "ListMemoryTypes 200 response" }, - "longTermMemory": { - "$ref": "#/components/schemas/LongTermMemoryConfig" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "extractionStrategy": { - "$ref": "#/components/schemas/ExtractionStrategy" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "summarization": { - "$ref": "#/components/schemas/SummarizationConfig" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "longTermMemoryExclusions": { - "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "customMemoryTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomMemoryType" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } }, - "description": "Custom memory types registered on the store." + "description": "NotImplementedError 501 response" }, - "extractionCadence": { - "$ref": "#/components/schemas/ExtractionCadenceConfig" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "name", - "status", - "storeId" - ] - }, - "StoreStatus": { - "type": "string", - "enum": [ - "PROVISIONING", - "READY", - "UNAVAILABLE" + "tags": [ + "memory-types" ] }, - "SummarizationConfig": { - "type": "object", - "description": "Configuration for session summarization.\nWhen enabled, long sessions are periodically condensed into a running summary\nwhile retaining the most recent events.", - "properties": { - "enabled": { - "type": "boolean", - "description": "Whether summarization is enabled for this store" - }, - "triggerStrategy": { - "$ref": "#/components/schemas/SummarizationTriggerStrategy" + "post": { + "description": "Register a custom memory type on a store. Its name, description and fields cannot\nchange afterwards. A name the store already registers is a 409.", + "operationId": "CreateMemoryType", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "eventCount": { - "$ref": "#/components/schemas/SummarizationThresholdConfig" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } } - }, - "required": [ - "enabled" - ] - }, - "SummarizationThresholdConfig": { - "type": "object", - "description": "Configuration for a summarization trigger.", - "properties": { - "threshold": { - "type": "integer", - "description": "The threshold value that triggers summarization", - "format": "int32" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomMemoryType" + } + } }, - "retainCount": { - "type": "integer", - "description": "Number of most recent events to retain after each summarization cycle.", - "format": "int32" - } + "required": true }, - "required": [ - "retainCount", - "threshold" - ] - }, - "SummarizationTriggerStrategy": { - "type": "string", - "description": "Strategy that determines when summarization is triggered.\nAdditional strategies such as token_count can be added later.", - "enum": [ - "event_count" - ] - }, - "UnexpectedErrorResponseContent": { - "type": "object", - "description": "The service failed with an unexpected internal error.", - "properties": { - "title": { - "type": "string", - "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4)." + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateMemoryTypeResponseContent" + } + } + }, + "description": "CreateMemoryType 201 response" }, - "status": { - "type": "integer", - "default": 500, - "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", - "format": "int32" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "detail": { - "type": "string", - "description": "A human-readable explanation specific to this occurrence of the problem." + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "instance": { - "type": "string", - "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "type": { - "$ref": "#/components/schemas/UnexpectedErrorType" - } - }, - "required": [ - "status", - "title", - "type" - ] - }, - "UnexpectedErrorType": { - "type": "string", - "description": "Problem type URI for unexpected internal errors.", - "enum": [ - "/errors/unexpected-error" - ] - }, - "UpdateExtractorRequestContent": { - "type": "object", - "properties": { - "expectedRevision": { - "type": "integer", - "format": "int64" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "name": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Customer-facing Extractor display name." + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" }, - "prompt": { - "type": "string" + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" }, - "destinationNamespaceId": { - "type": "string", - "description": "Empty string clears the destination namespace. Omitted leaves it unchanged.\nTyped as String so a clear is not rejected by StoreId @length(min: 1)." + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "enabled": { - "type": "boolean" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "expectedRevision" + "tags": [ + "memory-types" ] - }, - "UpdateExtractorResponseContent": { - "type": "object", - "properties": { - "id": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store-scoped Extractor identifier." - }, - "revision": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string", - "maxLength": 200, - "minLength": 1, - "description": "Customer-facing Extractor display name." + } + }, + "/iris/v1/agent-memory/stores/{storeId}/memory-types/{memoryTypeName}": { + "get": { + "description": "Get one of a store's custom memory types.", + "operationId": "GetMemoryType", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "source": { - "$ref": "#/components/schemas/ExtractorSource" + { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "in": "path", + "name": "memoryTypeName", + "required": true, + "schema": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } }, - "strategy": { - "$ref": "#/components/schemas/ExtractorStrategy" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetMemoryTypeResponseContent" + } + } + }, + "description": "GetMemoryType 200 response" }, - "memoryType": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Name of a custom memory type or field (1-64 chars). Must start with a letter,\nfollowed by letters, digits, underscores, or dashes." + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" }, - "prompt": { - "type": "string" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "destinationNamespaceId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "enabled": { - "type": "boolean" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "createdAt": { - "type": "string", - "format": "date-time" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "updatedAt": { - "type": "string", - "format": "date-time" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "createdAt", - "enabled", - "id", - "memoryType", - "name", - "prompt", - "revision", - "source", - "strategy", - "updatedAt" + "tags": [ + "memory-types" ] }, - "UpdateStoreRequestContent": { - "type": "object", - "properties": { - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[A-Za-z0-9._-]+$", - "description": "Operator-supplied store name." - }, - "shortMemory": { - "$ref": "#/components/schemas/ShortMemoryConfig" - }, - "longTermMemory": { - "$ref": "#/components/schemas/LongTermMemoryConfig" + "patch": { + "description": "Change a custom memory type's extraction strategy: its prompt, `enabled`, or both.\nOmitted members are unchanged. The type must already have a strategy.", + "operationId": "UpdateMemoryType", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } }, - "summarization": { - "$ref": "#/components/schemas/SummarizationConfig" + { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "in": "path", + "name": "memoryTypeName", + "required": true, + "schema": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } }, - "longTermMemoryExclusions": { - "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateMemoryTypeRequestContent" + } + } }, - "addCustomMemoryTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomMemoryType" + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateMemoryTypeResponseContent" + } + } }, - "description": "New custom memory types to append. Editing an existing type's prompt or\nenabled flag is done via updateCustomMemoryTypeStrategies; renaming,\nchanging fields, or removing a type is not supported." + "description": "UpdateMemoryType 200 response" }, - "updateCustomMemoryTypeStrategies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MemoryTypeStrategyUpdate" + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } }, - "description": "Strategy edits (prompt / enabled) to apply to existing custom memory types." - }, - "extractionCadence": { - "$ref": "#/components/schemas/ExtractionCadenceConfig" - } - } - }, - "UpdateStoreResponseContent": { - "type": "object", - "properties": { - "storeId": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[a-zA-Z0-9-]+$", - "description": "Store identifier (1-64 chars, alphanumeric and dashes). Generated IDs are 32-char UUIDs without dashes." - }, - "name": { - "type": "string", - "maxLength": 64, - "minLength": 1, - "pattern": "^[A-Za-z0-9._-]+$", - "description": "Operator-supplied store name." + "description": "BadRequestError 400 response" }, - "status": { - "$ref": "#/components/schemas/StoreStatus" - }, - "shortMemory": { - "$ref": "#/components/schemas/ShortMemoryConfig" + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" }, - "longTermMemory": { - "$ref": "#/components/schemas/LongTermMemoryConfig" + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" }, - "extractionStrategy": { - "$ref": "#/components/schemas/ExtractionStrategy" + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" }, - "summarization": { - "$ref": "#/components/schemas/SummarizationConfig" + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" }, - "longTermMemoryExclusions": { - "$ref": "#/components/schemas/LongTermMemoryExclusionsConfig" + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" }, - "customMemoryTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomMemoryType" + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } }, - "description": "Custom memory types registered on the store." + "description": "NotImplementedError 501 response" }, - "extractionCadence": { - "$ref": "#/components/schemas/ExtractionCadenceConfig" + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" } }, - "required": [ - "name", - "status", - "storeId" + "tags": [ + "memory-types" ] } - }, - "securitySchemes": { - "smithy.api.httpBearerAuth": { - "type": "http", - "description": "HTTP Bearer authentication", - "scheme": "Bearer" - } } }, "security": [ From 8464dfe928ceab36046af2d745062ddb254f7ca2 Mon Sep 17 00:00:00 2001 From: Robert Shelton Date: Fri, 30 Oct 2026 08:39:51 -0400 Subject: [PATCH 2/4] Iris docs: move the Agent Playbooks REST examples to the unified API Data-plane routes move to /iris/data/v1/agent-playbooks/playbooks/{playbookId}, including the MCP endpoint, discovery at entries/discover, and bulk deletion at faqs/bulk-delete and skills/bulk-delete. Lists and searches return items and nextCursor with no total; search takes minScore; proposals use revision, expectedRevision, state, entryKind and upper-case enums (INBOX, DESC, ADD, FAQ, ALREADY_PRESENT, PROMOTING); stale revisions return 412; preview budget is discovery.previewTokenBudget. Co-Authored-By: Claude Opus 5.5 --- .../context-engine/agent-playbooks/limits.md | 12 +++---- .../agent-playbooks/manage-faqs.md | 2 +- .../agent-playbooks/manage-skills.md | 2 +- .../ai/context-engine/agent-playbooks/mcp.md | 2 +- .../agent-playbooks/proposals.md | 12 +++---- .../agent-playbooks/quickstart.md | 2 +- .../agent-playbooks/retrieval.md | 6 ++-- local_examples/iris/playbooks/faqs/faqs.sh | 13 ++++--- .../iris/playbooks/faqs/faqs_delete.sh | 2 +- .../iris/playbooks/faqs/faqs_withdraw.sh | 2 +- .../langgraph_agent/langgraph_agent.mts | 2 +- .../langgraph_agent/langgraph_agent.py | 2 +- .../iris/playbooks/limits/limits.sh | 2 +- .../iris/playbooks/mcp/mcp_client.mts | 2 +- .../iris/playbooks/mcp/mcp_client.py | 2 +- .../iris/playbooks/mcp/mcp_client.sh | 2 +- .../playbooks/openai_agent/openai_agent.mts | 2 +- .../playbooks/openai_agent/openai_agent.py | 2 +- .../iris/playbooks/proposals/proposals.sh | 36 +++++++++---------- .../iris/playbooks/quickstart/quickstart.sh | 8 ++--- .../playbooks/quickstart/quickstart_delete.sh | 2 +- .../iris/playbooks/retrieval/retrieval.sh | 8 ++--- .../iris/playbooks/skills/skills.sh | 9 +++-- .../iris/playbooks/skills/skills_delete.sh | 2 +- .../iris/playbooks/skills/skills_withdraw.sh | 2 +- 25 files changed, 67 insertions(+), 71 deletions(-) diff --git a/content/develop/ai/context-engine/agent-playbooks/limits.md b/content/develop/ai/context-engine/agent-playbooks/limits.md index a0557d25e4..2237960d23 100644 --- a/content/develop/ai/context-engine/agent-playbooks/limits.md +++ b/content/develop/ai/context-engine/agent-playbooks/limits.md @@ -64,7 +64,7 @@ Pins consume discovery slots and preview budget. The preview ceiling applies to Follow a list response's next cursor until it is absent, even if a page is empty. Keep the collection, filters, and ordering consistent between pages. Lists reflect concurrent changes and do not represent a fixed snapshot. -Entry and proposal lists can include a separately measured first-page `total`. Absence means unknown, not zero. Cursored pages and version history omit totals. Use the cursor, not the count or page length, to decide when to stop. See [List entries and inspect history]({{< relref "/develop/ai/context-engine/agent-playbooks/manage-faqs#list-entries-and-inspect-history" >}}) for examples. +List responses return `items` and `nextCursor` and do not include a total count. Use the cursor, not the page length, to decide when to stop. See [List entries and inspect history]({{< relref "/develop/ai/context-engine/agent-playbooks/manage-faqs#list-entries-and-inspect-history" >}}) for examples. ## Proposal and evidence limits @@ -92,6 +92,7 @@ HTTP errors include a status and machine-readable `type`. Use the type to choose | `403` | The caller lacks access. | Check tenant, playbook, and action grants. `write` does not include `publish`. | | `404` | The requested resource is unavailable. | Check identifiers and retention. Rediscover a previously selected skill once. | | `409` | Content or review state conflicts with the request. | Inspect the error type and current state before changing the request. | +| `412` | The proposal revision you supplied is no longer current (`/errors/revision-conflict`). | Read the proposal again, using `currentRevision` from the error, and review the current candidate before resubmitting. | | `413` | Content exceeds a payload limit. | Reduce the package, metadata, answer, or evidence payload. | | `423` | The playbook is suspended. | Ask the administrator to inspect its state. | | `424` | A required dependency failed. | Check playbook health and ask the administrator to inspect the dependency. | @@ -117,10 +118,9 @@ The `409` error type identifies the recovery step: | `/errors/entry-key-conflict` | Use the existing entry or choose another key. | | `/errors/content-limit-exceeded` | Free retained capacity or confirm a higher supported deployment limit. | | `/errors/pinned-entry-unavailable` | Correct or remove the pin. | -| `/errors/proposal-already-exists` | Inspect `existingProposalId` or attach evidence to that proposal. | +| `/errors/proposal-already-exists` | Inspect `existingId` or attach evidence to that proposal. | | `/errors/proposal-evidence-conflict` | Retry the original evidence payload or use a new evidence identifier for a new observation. | | `/errors/proposal-evidence-capacity` | Review the proposal with its retained evidence; additional evidence does not fit. | -| `/errors/proposal-revision-conflict` | Read and review the current candidate before resubmitting. | | `/errors/proposal-trashed` | Restore the proposal before modifying or accepting it. | | `/errors/proposal-open` | Dismiss the proposal before purging it. | | `/errors/proposal-promotion-locked` | Resume acceptance or use its recorded FAQ. Candidate edits and evidence changes are locked. | @@ -131,7 +131,7 @@ Use bounded retries for reads and transient failures. Proposal acceptance can re A timeout, including `408`, does not prove a create or append failed. Read state before retrying to avoid another entry or version. Check the Python SDK retry configuration when controlling write retries. -Bulk deletion is not atomic across the batch. Earlier deletions can remain applied after a later failure. Retrying the same batch is safe because absent entries are ignored. +Bulk deletion is not atomic across the batch. The response lists removed entries in `deleted` and entries it couldn't delete in `errors`. Earlier deletions remain applied after a later failure. Retrying the same batch is safe because absent entries are ignored. ## Remove content in bulk @@ -139,8 +139,8 @@ Use a key with `write` permission for bulk deletion. Choose the entry type befor | Task | Python method | HTTP request | |:-----|:--------------|:-------------| -| Delete selected FAQ entries and all their versions | `delete_faqs(entry_ids=...)` | `DELETE /v1/playbooks/{playbookId}/faqs` with an `entryIds` array | -| Delete selected skills, versions, and files | `delete_skills(entry_ids=...)` | `DELETE /v1/playbooks/{playbookId}/skills` with an `entryIds` array | +| Delete selected FAQ entries and all their versions | `delete_faqs(entry_ids=...)` | `POST /iris/data/v1/agent-playbooks/playbooks/{playbookId}/faqs/bulk-delete` with an `entryIds` array | +| Delete selected skills, versions, and files | `delete_skills(entry_ids=...)` | `POST /iris/data/v1/agent-playbooks/playbooks/{playbookId}/skills/bulk-delete` with an `entryIds` array | Bulk deletion accepts 1–100 entry identifiers of the selected type. The data plane does not provide an operation to clear an entire playbook. An administrator can clear entries, proposals, or both through the control plane. diff --git a/content/develop/ai/context-engine/agent-playbooks/manage-faqs.md b/content/develop/ai/context-engine/agent-playbooks/manage-faqs.md index 85a9bb3867..1dfef05473 100644 --- a/content/develop/ai/context-engine/agent-playbooks/manage-faqs.md +++ b/content/develop/ai/context-engine/agent-playbooks/manage-faqs.md @@ -92,7 +92,7 @@ Republish the first version to roll back. Use `list_faqs` to list entries, including unpublished ones, and `get_faq` to read a summary. Both require `read`. Summaries show the latest version number and any publication, without draft content. -Follow the pagination cursor until it is absent, even after an empty page. Keep filters and sort settings unchanged. The optional first-page `total` is a separately measured count; absence means unknown, not zero. Lists can change while you page through them. +Follow the pagination cursor until it is absent, even after an empty page. Keep filters and sort settings unchanged. Responses return `items` and `nextCursor` and don't include a total count. Lists can change while you page through them. CLI lists and version history follow all cursors automatically and return an array. Use `--page` for one page with `nextCursor`, and `--cursor` to continue it. The CLI's version output currently omits `contentDigest`; use an SDK or cURL example when you need that field. diff --git a/content/develop/ai/context-engine/agent-playbooks/manage-skills.md b/content/develop/ai/context-engine/agent-playbooks/manage-skills.md index 667bf12a27..cf90ad62b4 100644 --- a/content/develop/ai/context-engine/agent-playbooks/manage-skills.md +++ b/content/develop/ai/context-engine/agent-playbooks/manage-skills.md @@ -108,7 +108,7 @@ To verify file content, compare the descriptor's SHA-256 (Secure Hash Algorithm Use `list_skills` to inventory entries and `get_skill` to inspect one entry's summary. These operations require `read`; draft content and full version history require `write` or `publish`. To resolve a skill by its entry key or compare latest and published content digests, use the shared [entry lookup operation]({{< relref "/develop/ai/context-engine/agent-playbooks/manage-faqs#look-up-entry-state" >}}). -Follow cursors even after empty pages, and keep filters and ordering unchanged. An absent first-page `total` means the count is unknown. See [pagination behavior]({{< relref "/develop/ai/context-engine/agent-playbooks/limits#retrieval-limits" >}}). +Follow cursors even after empty pages, and keep filters and ordering unchanged. Responses return `items` and `nextCursor` and don't include a total count. See [pagination behavior]({{< relref "/develop/ai/context-engine/agent-playbooks/limits#retrieval-limits" >}}). {{< clients-example set="iris_playbook_skills" step="playbook-skill-list" description="" lang_filter="Python (Iris),cURL (Iris),CLI (Iris)" footer="hide" />}} diff --git a/content/develop/ai/context-engine/agent-playbooks/mcp.md b/content/develop/ai/context-engine/agent-playbooks/mcp.md index 9f7a15f08f..5e5bb2c3df 100644 --- a/content/develop/ai/context-engine/agent-playbooks/mcp.md +++ b/content/develop/ai/context-engine/agent-playbooks/mcp.md @@ -41,7 +41,7 @@ Use a client that supports Streamable HTTP and custom request headers: | Setting | Value | |:--------|:------| | Transport | Streamable HTTP | -| Endpoint | `/v1/playbooks//mcp` | +| Endpoint | `/iris/data/v1/agent-playbooks/playbooks//mcp` | | Request header | `Authorization: Bearer ` | The endpoint must be reachable from the client runtime. A hosted client needs an HTTPS endpoint reachable from its provider; a local address works for clients on the same host. Keep the playbook key in connection settings and out of agent instructions. diff --git a/content/develop/ai/context-engine/agent-playbooks/proposals.md b/content/develop/ai/context-engine/agent-playbooks/proposals.md index f435d05be6..1489925781 100644 --- a/content/develop/ai/context-engine/agent-playbooks/proposals.md +++ b/content/develop/ai/context-engine/agent-playbooks/proposals.md @@ -34,7 +34,7 @@ For this walkthrough, give `PLAYBOOK_API_KEY` all three permissions and follow t A key with `read` permission can list, search, and inspect proposals. The inbox contains candidates awaiting review and any acceptance still in progress. Only open candidates can be edited. -For software development kit (SDK) and cURL lists, follow the cursor until it is absent, even after an empty page. Keep the view and sort settings unchanged; an absent `total` means unknown. The command-line interface (CLI) follows cursors automatically. Use `--page` for one page with `items` and `nextCursor`, then `--cursor` to continue. +For software development kit (SDK) and cURL lists, follow the cursor until it is absent, even after an empty page. Keep the view and sort settings unchanged. Responses return `items` and `nextCursor` and don't include a total count. The command-line interface (CLI) follows cursors automatically. Use `--page` for one page with `items` and `nextCursor`, then `--cursor` to continue. {{< clients-example set="iris_playbook_proposals" step="playbook-proposal-inbox" description="" lang_filter="Python (Iris),cURL (Iris),CLI (Iris)" footer="hide" />}} @@ -46,7 +46,7 @@ Search before submitting another candidate. Compare similar questions to decide Write a self-contained question and answer. Add intents for the task and attributes for its audience, then call `create_proposal` with an `add` action targeting `newEntry`. You can supply an entry key for the resulting FAQ and immutable source context that a reviewer can check. -Save the proposal identifier and `proposalRevision`. Use the revision to identify the candidate you edit or accept. +Save the proposal identifier and `revision`. Use the revision to identify the candidate you edit or accept. {{< clients-example set="iris_playbook_proposals" step="playbook-proposal-create" description="" lang_filter="Python (Iris),cURL (Iris),CLI (Iris)" footer="hide" />}} @@ -54,7 +54,7 @@ The CLI takes a flat FAQ candidate file and a separate source file in JavaScript ### Handle an existing candidate -If creation or replacement returns `409` with type `/errors/proposal-already-exists`, read the existing proposal. Python exposes its identifier as `error.data.existing_proposal_id` on `PlaybookConflictErrorResponseContent`. +If creation or replacement returns `409` with type `/errors/proposal-already-exists`, read the existing proposal. The error body names it in `existingId`; Python exposes it as `error.data.existing_id` on `ConflictErrorResponseContent`. If the open candidate addresses the same need, [attach evidence]({{< relref "/develop/ai/context-engine/agent-playbooks/proposals#attach-evidence" >}}) to it rather than creating another suggestion. Review its current revision before editing or accepting it. @@ -71,7 +71,7 @@ Use `submit_proposal_evidence` to add another observation to an open proposal. F Include a supporting passage and a reference the reviewer can check. Redis Agent Playbooks does not independently verify caller-supplied attribution. An evidence count measures observations, not correctness or independent users. -Evidence is immutable. Retrying the same identifier and payload returns `alreadyPresent`. Reusing that identifier for changed content returns a conflict. Use a new identifier for a new observation. +Evidence is immutable. Retrying the same identifier and payload returns the disposition `ALREADY_PRESENT`; new evidence returns `ADDED`. Reusing that identifier for changed content returns a conflict. Use a new identifier for a new observation. The creation source explains the first suggestion and does not increase `evidenceCount`. Attached evidence stays with the proposal; acceptance does not copy it into the FAQ. Check [evidence limits]({{< relref "/develop/ai/context-engine/agent-playbooks/limits#proposal-and-evidence-limits" >}}) before attaching large passages. @@ -84,7 +84,7 @@ This example attaches a policy excerpt. The cURL and CLI tabs use `openssl` to g 1. Retrieve the complete proposal and its evidence with `get_proposal`. 1. Check that the sources support the answer, its conditions, and its intended audience. 1. Check for sensitive or conversation-specific details that should not become reusable guidance. -1. Replace the candidate with `replace_proposal` if it needs changes. Supply the complete action and `expectedProposalRevision` for the revision you read. +1. Replace the candidate with `replace_proposal` if it needs changes. Supply the complete action and `expectedRevision` for the revision you read. 1. Review the returned candidate and record its new revision. Editing preserves evidence. If another reviewer changes the candidate, the revision check fails; review the current answer before trying again. @@ -111,7 +111,7 @@ Test dismissal and restoration before accepting the sample. Purging instead ends Call `accept_proposal` with the revision you reviewed. Acceptance creates one unpublished FAQ. Use the entry identifier and version in `result.versionCreated` to read that FAQ, then [publish the reviewed version]({{< relref "/develop/ai/context-engine/agent-playbooks/manage-faqs#publish-a-version" >}}) with a key that has `publish` permission. -A proposal being accepted (`promoting`) or already accepted (`promoted`) cannot be edited. If acceptance is interrupted, retry it rather than creating another FAQ. The returned receipt is historical: it does not contain the answer or confirm that the FAQ still exists. Inspect the FAQ before acting on a retried result. +A proposal being accepted (state `PROMOTING`) or already accepted (`PROMOTED`) cannot be edited. If acceptance is interrupted, retry it rather than creating another FAQ. The returned receipt is historical: it does not contain the answer or confirm that the FAQ still exists. Inspect the FAQ before acting on a retried result. If your client cannot recognize the result type, inspect the result or upgrade the client before publishing. diff --git a/content/develop/ai/context-engine/agent-playbooks/quickstart.md b/content/develop/ai/context-engine/agent-playbooks/quickstart.md index c5790b556c..8f80483fa2 100644 --- a/content/develop/ai/context-engine/agent-playbooks/quickstart.md +++ b/content/develop/ai/context-engine/agent-playbooks/quickstart.md @@ -42,7 +42,7 @@ jq --version ## Save connection values -Export these values in the shell where you run the examples. Use the endpoint's base address, including `https://`, without the `/v1/playbooks/...` path. +Export these values in the shell where you run the examples. Use the endpoint's base address, including `https://`, without the `/iris/data/v1/agent-playbooks/...` path. ```bash export PLAYBOOK_URL='' diff --git a/content/develop/ai/context-engine/agent-playbooks/retrieval.md b/content/develop/ai/context-engine/agent-playbooks/retrieval.md index f18e39e05c..35fbe3bfd4 100644 --- a/content/develop/ai/context-engine/agent-playbooks/retrieval.md +++ b/content/develop/ai/context-engine/agent-playbooks/retrieval.md @@ -66,7 +66,7 @@ Your administrator sets the playbook controls: | `discovery.faqMinimumScore` | `0.7` | Minimum similarity for discovered FAQ matches. | | `discovery.skillMinimumScore` | `0.7` | Minimum similarity for discovered skill matches. | | `discovery.maxResults` | `10` | Combined result ceiling for pins and discovered matches. | -| `discovery.maxPreviewTokens` | Disabled | Estimated token ceiling for the discovery response. | +| `discovery.previewTokenBudget` | Disabled | Estimated token ceiling for the discovery response. It applies only when `discovery.previewTokenBudgetEnabled` is `true`. | Discovery has no per-request similarity override. An administrator can adjust the playbook thresholds. @@ -123,7 +123,7 @@ Use an SDK or cURL for this reader-only operation. The published CLI's skill-loa ## Search -Search returns ranked `matches` of one entry type. Use it to find an answer, select a skill, or tune retrieval per request. +Search returns ranked `items` of one entry type. Use it to find an answer, select a skill, or tune retrieval per request. | Operation | Use it when | Result | |:----------|:------------|:-------| @@ -146,7 +146,7 @@ Search accepts these request controls. The table uses HTTP field names. |:--------|:--------|:----------| | `query` | Required | Describe the task to match semantically. | | `filter` | None | Restrict matches by entry attributes, such as locale or topic. | -| `minimumScore` | The playbook's threshold for that entry type; initially `0.7` | Set a similarity floor from `0` to `1` for this request. | +| `minScore` | The playbook's threshold for that entry type; initially `0.7` | Set a similarity floor from `0` to `1` for this request. | | `limit` | `discovery.maxResults`; initially `10` | Request 1–50 results. An explicit search limit is not capped by the playbook's discovery limit. | The threshold defaults come from `discovery.faqMinimumScore` and `discovery.skillMinimumScore`. Your administrator can change them. Search does not use discovery pins or the discovery preview budget. diff --git a/local_examples/iris/playbooks/faqs/faqs.sh b/local_examples/iris/playbooks/faqs/faqs.sh index 0a5f9ffb66..5c323680d9 100644 --- a/local_examples/iris/playbooks/faqs/faqs.sh +++ b/local_examples/iris/playbooks/faqs/faqs.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . @@ -52,7 +52,7 @@ curl --fail-with-body --silent --show-error \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"query":"Where can I see how my refund is progressing?","filter":{"eq":{"name":"locale","value":"en-US"}},"limit":5}' \ - | jq '.matches[] | {entryId, version, score, answer: .faq.answer}' + | jq '.items[] | {entryId, version, score, answer: .faq.answer}' # STEP_END # STEP_START playbook-faq-update @@ -84,12 +84,11 @@ curl --fail-with-body --silent --show-error \ # STEP_START playbook-faq-list CURSOR='' while true; do - PAGE_ARGS=(--data-urlencode sortBy=updatedAt --data-urlencode sortOrder=desc --data-urlencode limit=50) + PAGE_ARGS=(--data-urlencode sortBy=updatedAt --data-urlencode sortOrder=DESC --data-urlencode limit=50) if [[ -n "$CURSOR" ]]; then PAGE_ARGS+=(--data-urlencode "cursor=$CURSOR"); fi curl --fail-with-body --silent --show-error --get "$PLAYBOOK_API/faqs" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" "${PAGE_ARGS[@]}" > faq-page.json - if [[ -z "$CURSOR" ]]; then jq '.total // "unknown"' faq-page.json; fi - jq '.faqs[] | {entryId, latestVersion, publication}' faq-page.json + jq '.items[] | {entryId, latestVersion, publication}' faq-page.json CURSOR=$(jq -r '.nextCursor // empty' faq-page.json) [[ -n "$CURSOR" ]] || break done @@ -102,7 +101,7 @@ while true; do if [[ -n "$CURSOR" ]]; then PAGE_ARGS+=(--data-urlencode "cursor=$CURSOR"); fi curl --fail-with-body --silent --show-error --get "$PLAYBOOK_API/faqs/$FAQ_ID/versions" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" "${PAGE_ARGS[@]}" > faq-versions.json - jq '.versions[] | {version, contentDigest, content}' faq-versions.json + jq '.items[] | {version, contentDigest, content}' faq-versions.json CURSOR=$(jq -r '.nextCursor // empty' faq-versions.json) [[ -n "$CURSOR" ]] || break done @@ -114,5 +113,5 @@ jq -n --arg id "$FAQ_ID" '{references: [{entryId: $id}, {entryKey: "refund-statu -X POST "$PLAYBOOK_API/entries/lookup" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' --data-binary @- \ - | jq '{maxVersions, results}' + | jq '{maxVersions, items}' # STEP_END diff --git a/local_examples/iris/playbooks/faqs/faqs_delete.sh b/local_examples/iris/playbooks/faqs/faqs_delete.sh index 8b786251aa..2c925bc629 100644 --- a/local_examples/iris/playbooks/faqs/faqs_delete.sh +++ b/local_examples/iris/playbooks/faqs/faqs_delete.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . diff --git a/local_examples/iris/playbooks/faqs/faqs_withdraw.sh b/local_examples/iris/playbooks/faqs/faqs_withdraw.sh index 34faee2dfa..1789d0f0c3 100644 --- a/local_examples/iris/playbooks/faqs/faqs_withdraw.sh +++ b/local_examples/iris/playbooks/faqs/faqs_withdraw.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . diff --git a/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.mts b/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.mts index ac67b6e168..bf677ee75b 100644 --- a/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.mts +++ b/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.mts @@ -51,7 +51,7 @@ async function main() { prefixToolNameWithServerName: false, servers: { playbook: { - url: `${url}/v1/playbooks/${playbookId}/mcp`, + url: `${url}/iris/data/v1/agent-playbooks/playbooks/${playbookId}/mcp`, headers: { Authorization: `Bearer ${apiKey}` }, }, }, diff --git a/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.py b/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.py index 6716b600a1..1a35dc381f 100644 --- a/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.py +++ b/local_examples/iris/playbooks/langgraph_agent/langgraph_agent.py @@ -65,7 +65,7 @@ async def respond(state: Turn): if not state["context"]: return {"reply": state["reply"]} transport = StreamableHttpTransport( - f"{url}/v1/playbooks/{playbook_id}/mcp", + f"{url}/iris/data/v1/agent-playbooks/playbooks/{playbook_id}/mcp", headers={"Authorization": f"Bearer {api_key}"}, ) async with MCPAdapter(transport) as mcp: diff --git a/local_examples/iris/playbooks/limits/limits.sh b/local_examples/iris/playbooks/limits/limits.sh index 1b1a1245aa..e40a8f119d 100644 --- a/local_examples/iris/playbooks/limits/limits.sh +++ b/local_examples/iris/playbooks/limits/limits.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . diff --git a/local_examples/iris/playbooks/mcp/mcp_client.mts b/local_examples/iris/playbooks/mcp/mcp_client.mts index 4ea2303e2b..bb9bf45c55 100644 --- a/local_examples/iris/playbooks/mcp/mcp_client.mts +++ b/local_examples/iris/playbooks/mcp/mcp_client.mts @@ -17,7 +17,7 @@ function readResult(value: Awaited>) { if (!text || text.type !== "text") throw new Error("Playbook tool returned no JSON text."); return JSON.parse(text.text); } -const url = `${requiredEnv("PLAYBOOK_URL").replace(/\/+$/, "")}/v1/playbooks/${requiredEnv("PLAYBOOK_ID")}/mcp`; +const url = `${requiredEnv("PLAYBOOK_URL").replace(/\/+$/, "")}/iris/data/v1/agent-playbooks/playbooks/${requiredEnv("PLAYBOOK_ID")}/mcp`; const client = new Client({ name: "playbook-example", version: "1.0.0" }); const transport = new StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: { Authorization: `Bearer ${requiredEnv("PLAYBOOK_API_KEY")}` } }, diff --git a/local_examples/iris/playbooks/mcp/mcp_client.py b/local_examples/iris/playbooks/mcp/mcp_client.py index 4bb8a3fd82..68d881ea18 100644 --- a/local_examples/iris/playbooks/mcp/mcp_client.py +++ b/local_examples/iris/playbooks/mcp/mcp_client.py @@ -18,7 +18,7 @@ def read_result(result): async def main(): - url = f"{os.environ['PLAYBOOK_URL'].rstrip('/')}/v1/playbooks/{os.environ['PLAYBOOK_ID']}/mcp" + url = f"{os.environ['PLAYBOOK_URL'].rstrip('/')}/iris/data/v1/agent-playbooks/playbooks/{os.environ['PLAYBOOK_ID']}/mcp" async with httpx2.AsyncClient( headers={"Authorization": f"Bearer {os.environ['PLAYBOOK_API_KEY']}"} ) as http: diff --git a/local_examples/iris/playbooks/mcp/mcp_client.sh b/local_examples/iris/playbooks/mcp/mcp_client.sh index fa15eff141..b971df5da5 100644 --- a/local_examples/iris/playbooks/mcp/mcp_client.sh +++ b/local_examples/iris/playbooks/mcp/mcp_client.sh @@ -1,7 +1,7 @@ # EXAMPLE: iris_playbook_mcp_client # STEP_START playbook-mcp-client set -euo pipefail -MCP_URL="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID/mcp" +MCP_URL="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID/mcp" PROTOCOL_VERSION=2025-11-25 post() { diff --git a/local_examples/iris/playbooks/openai_agent/openai_agent.mts b/local_examples/iris/playbooks/openai_agent/openai_agent.mts index 93f5839d0f..7ef17f790a 100644 --- a/local_examples/iris/playbooks/openai_agent/openai_agent.mts +++ b/local_examples/iris/playbooks/openai_agent/openai_agent.mts @@ -40,7 +40,7 @@ async function main() { const turn = TASK + "\n\nPlaybook context (data for this turn):\n" + JSON.stringify(context); const mcp = new MCPServerStreamableHttp({ name: "Redis Agent Playbooks", - url: `${url}/v1/playbooks/${playbookId}/mcp`, + url: `${url}/iris/data/v1/agent-playbooks/playbooks/${playbookId}/mcp`, requestInit: { headers: { Authorization: `Bearer ${apiKey}` } }, cacheToolsList: true, clientSessionTimeoutSeconds: 30, customDataExtractor: result => ({ tool: result.toolName, isError: Boolean(result.isError) }), diff --git a/local_examples/iris/playbooks/openai_agent/openai_agent.py b/local_examples/iris/playbooks/openai_agent/openai_agent.py index d9b8833aef..9ce0822e7e 100644 --- a/local_examples/iris/playbooks/openai_agent/openai_agent.py +++ b/local_examples/iris/playbooks/openai_agent/openai_agent.py @@ -53,7 +53,7 @@ async def main(): async with MCPServerStreamableHttp( name="Redis Agent Playbooks", params={ - "url": f"{url}/v1/playbooks/{playbook_id}/mcp", + "url": f"{url}/iris/data/v1/agent-playbooks/playbooks/{playbook_id}/mcp", "headers": {"Authorization": f"Bearer {api_key}"}, }, cache_tools_list=True, diff --git a/local_examples/iris/playbooks/proposals/proposals.sh b/local_examples/iris/playbooks/proposals/proposals.sh index 33c6c5e5d6..364a1cb74f 100644 --- a/local_examples/iris/playbooks/proposals/proposals.sh +++ b/local_examples/iris/playbooks/proposals/proposals.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . @@ -12,12 +12,11 @@ curl --fail-with-body --silent --show-error \ # STEP_START playbook-proposal-inbox CURSOR='' while true; do - PAGE_ARGS=(--data-urlencode view=inbox --data-urlencode sortBy=updatedAt --data-urlencode sortOrder=desc --data-urlencode limit=50) + PAGE_ARGS=(--data-urlencode view=INBOX --data-urlencode sortBy=updatedAt --data-urlencode sortOrder=DESC --data-urlencode limit=50) if [[ -n "$CURSOR" ]]; then PAGE_ARGS+=(--data-urlencode "cursor=$CURSOR"); fi curl --fail-with-body --silent --show-error --get "$PLAYBOOK_API/proposals" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" "${PAGE_ARGS[@]}" > inbox.json - if [[ -z "$CURSOR" ]]; then jq '.total // "unknown"' inbox.json; fi - jq '.proposals[] | {proposalId, status, evidenceCount, action}' inbox.json + jq '.items[] | {proposalId, state, evidenceCount, action}' inbox.json CURSOR=$(jq -r '.nextCursor // empty' inbox.json) [[ -n "$CURSOR" ]] || break done @@ -28,13 +27,13 @@ curl --fail-with-body --silent --show-error \ -X POST "$PLAYBOOK_API/proposals/search" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ - --data '{"query":"Contact support about a missing refund","minimumScore":0.7,"actionType":"add","entryType":"faq","limit":5}' \ - | jq '.matches[] | {proposalId: .proposal.proposalId, score, action: .proposal.action}' + --data '{"query":"Contact support about a missing refund","minScore":0.7,"actionType":"ADD","entryKind":"FAQ","limit":5}' \ + | jq '.items[] | {proposalId: .proposal.proposalId, score, action: .proposal.action}' # STEP_END # STEP_START playbook-proposal-create cat > proposal.json <<'JSON' -{"source":{"type":"document","reference":{"documentId":"sample-refund-policy"}}, +{"source":{"kind":"document","reference":{"documentId":"sample-refund-policy"}}, "action":{"add":{ "target":{"newEntry":{}}, "candidate":{"content":{ @@ -52,7 +51,7 @@ curl --fail-with-body --silent --show-error \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' --data-binary @proposal.json > proposal-created.json PROPOSAL_ID=$(jq -er '.proposalId' proposal-created.json) -jq '{proposalId, proposalRevision}' proposal-created.json +jq '{proposalId, revision}' proposal-created.json # STEP_END # STEP_START playbook-proposal-evidence @@ -61,7 +60,7 @@ jq -n --arg observedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{ observedAt: $observedAt, producer: {name: "docs-example", promptVersion: "refund-review-v1"}, source: { - type: "document", + kind: "document", reference: {documentId: "sample-refund-policy"}, content: {excerpt: "For refund inquiries, collect the order number and request date. Do not request full card details."} } @@ -80,16 +79,16 @@ jq . reviewed.json # STEP_END # STEP_START playbook-proposal-replace -jq --argjson revision "$(jq -er '.proposalRevision' reviewed.json)" ' +jq --argjson revision "$(jq -er '.revision' reviewed.json)" ' {action} | .action.add.candidate.content.payload.faq.answer += " Do not send full card details." | - .expectedProposalRevision = $revision + .expectedRevision = $revision ' reviewed.json > proposal-update.json curl --fail-with-body --silent --show-error \ -X PATCH "$PLAYBOOK_API/proposals/$PROPOSAL_ID" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' --data-binary @proposal-update.json > revised.json -jq '{proposalRevision, action}' revised.json +jq '{revision, action}' revised.json # STEP_END # STEP_START playbook-proposal-trash @@ -97,10 +96,10 @@ curl --fail-with-body --silent --show-error \ -X PUT "$PLAYBOOK_API/proposals/$PROPOSAL_ID/dismissal" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ - --data "$(jq '{expectedProposalRevision: .proposalRevision}' revised.json)" | jq .status + --data "$(jq '{expectedRevision: .revision}' revised.json)" | jq .state curl --fail-with-body --silent --show-error \ -X DELETE "$PLAYBOOK_API/proposals/$PROPOSAL_ID/dismissal" \ - -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq .status + -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq .state # To purge instead of restoring, DELETE /proposals/$PROPOSAL_ID. # STEP_END @@ -108,7 +107,7 @@ curl --fail-with-body --silent --show-error \ curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/proposals/$PROPOSAL_ID" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" > final-review.json -jq '{action, evidence, proposalRevision}' final-review.json +jq '{action, evidence, revision}' final-review.json # STEP_END # STEP_START playbook-proposal-accept @@ -116,7 +115,7 @@ curl --fail-with-body --silent --show-error \ -X POST "$PLAYBOOK_API/proposals/$PROPOSAL_ID/acceptance" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ - --data "$(jq '{expectedProposalRevision: .proposalRevision}' final-review.json)" > accepted.json + --data "$(jq '{expectedRevision: .revision}' final-review.json)" > accepted.json ACCEPTED_FAQ_ID=$(jq -er '.result.versionCreated.entryId' accepted.json) ACCEPTED_VERSION=$(jq -er '.result.versionCreated.version' accepted.json) curl --fail-with-body --silent --show-error \ @@ -136,12 +135,11 @@ curl --fail-with-body --silent --show-error \ # STEP_START playbook-proposal-history CURSOR='' while true; do - PAGE_ARGS=(--data-urlencode view=trash --data-urlencode sortBy=updatedAt --data-urlencode sortOrder=desc --data-urlencode limit=50) + PAGE_ARGS=(--data-urlencode view=TRASH --data-urlencode sortBy=updatedAt --data-urlencode sortOrder=DESC --data-urlencode limit=50) if [[ -n "$CURSOR" ]]; then PAGE_ARGS+=(--data-urlencode "cursor=$CURSOR"); fi curl --fail-with-body --silent --show-error --get "$PLAYBOOK_API/proposals" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" "${PAGE_ARGS[@]}" > trash.json - if [[ -z "$CURSOR" ]]; then jq '.total // "unknown"' trash.json; fi - jq '.proposals[] | {proposalId, status, evidenceCount, action}' trash.json + jq '.items[] | {proposalId, state, evidenceCount, action}' trash.json CURSOR=$(jq -r '.nextCursor // empty' trash.json) [[ -n "$CURSOR" ]] || break done diff --git a/local_examples/iris/playbooks/quickstart/quickstart.sh b/local_examples/iris/playbooks/quickstart/quickstart.sh index 05a4c7e9ee..d7e1d4ddf0 100644 --- a/local_examples/iris/playbooks/quickstart/quickstart.sh +++ b/local_examples/iris/playbooks/quickstart/quickstart.sh @@ -3,7 +3,7 @@ set -euo pipefail # STEP_START playbook-connect set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . @@ -51,12 +51,12 @@ curl --fail-with-body --silent --show-error \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"query":"Where can I see how my refund is progressing?","filter":{"eq":{"name":"locale","value":"en-US"}},"limit":5}' \ - | jq '.matches[] | {entryId, version, score, answer: .faq.answer}' + | jq '.items[] | {entryId, version, score, answer: .faq.answer}' # STEP_END # STEP_START playbook-quickstart-discover curl --fail-with-body --silent --show-error \ - -X POST "$PLAYBOOK_API/discover" \ + -X POST "$PLAYBOOK_API/entries/discover" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"query":"Help a customer find their refund status","filter":{"eq":{"name":"topic","value":"refund"}},"limit":5}' | jq . @@ -83,5 +83,5 @@ curl --fail-with-body --silent --show-error \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"query":"Where can I see how my refund is progressing?","filter":{"eq":{"name":"locale","value":"en-US"}},"limit":5}' \ - | jq --arg id "$FAQ_ID" '.matches[] | select(.entryId == $id) | {version, answer: .faq.answer}' + | jq --arg id "$FAQ_ID" '.items[] | select(.entryId == $id) | {version, answer: .faq.answer}' # STEP_END diff --git a/local_examples/iris/playbooks/quickstart/quickstart_delete.sh b/local_examples/iris/playbooks/quickstart/quickstart_delete.sh index 9feeeeeb55..8568a677b9 100644 --- a/local_examples/iris/playbooks/quickstart/quickstart_delete.sh +++ b/local_examples/iris/playbooks/quickstart/quickstart_delete.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . diff --git a/local_examples/iris/playbooks/retrieval/retrieval.sh b/local_examples/iris/playbooks/retrieval/retrieval.sh index c9a7ca28f6..b3a2804714 100644 --- a/local_examples/iris/playbooks/retrieval/retrieval.sh +++ b/local_examples/iris/playbooks/retrieval/retrieval.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . @@ -11,7 +11,7 @@ curl --fail-with-body --silent --show-error \ # STEP_START playbook-retrieval-discover curl --fail-with-body --silent --show-error \ - -X POST "$PLAYBOOK_API/discover" \ + -X POST "$PLAYBOOK_API/entries/discover" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"query":"Draft a reply for a customer whose refund shows Processing","limit":5}' | jq . @@ -19,7 +19,7 @@ curl --fail-with-body --silent --show-error \ # STEP_START playbook-retrieval-pin curl --fail-with-body --silent --show-error \ - -X POST "$PLAYBOOK_API/discover" \ + -X POST "$PLAYBOOK_API/entries/discover" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ --data "$(jq -n --arg id "$PLAYBOOK_SKILL_ID" '{query: "Draft a reply for a customer whose refund shows Processing", pinnedEntries: [{entryId: $id}], limit: 5}')" > discovery.json @@ -61,7 +61,7 @@ curl --fail-with-body --silent --show-error \ -X POST "$PLAYBOOK_API/faqs/search" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" \ -H 'Content-Type: application/json' \ - --data '{"query":"Where is my refund?","minimumScore":0.75,"limit":3}' | jq .matches + --data '{"query":"Where is my refund?","minScore":0.75,"limit":3}' | jq .items # STEP_END # STEP_START playbook-retrieval-filter diff --git a/local_examples/iris/playbooks/skills/skills.sh b/local_examples/iris/playbooks/skills/skills.sh index 1d74a40da4..2b1813fc3a 100644 --- a/local_examples/iris/playbooks/skills/skills.sh +++ b/local_examples/iris/playbooks/skills/skills.sh @@ -29,7 +29,7 @@ zip -r refund-support-reply.zip refund-support-reply # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . @@ -92,12 +92,11 @@ curl --fail-with-body --silent --show-error \ # STEP_START playbook-skill-list CURSOR='' while true; do - PAGE_ARGS=(--data-urlencode sortBy=updatedAt --data-urlencode sortOrder=desc --data-urlencode limit=50) + PAGE_ARGS=(--data-urlencode sortBy=updatedAt --data-urlencode sortOrder=DESC --data-urlencode limit=50) if [[ -n "$CURSOR" ]]; then PAGE_ARGS+=(--data-urlencode "cursor=$CURSOR"); fi curl --fail-with-body --silent --show-error --get "$PLAYBOOK_API/skills" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" "${PAGE_ARGS[@]}" > skill-page.json - if [[ -z "$CURSOR" ]]; then jq '.total // "unknown"' skill-page.json; fi - jq '.skills[] | {entryId, latestVersion, publication}' skill-page.json + jq '.items[] | {entryId, latestVersion, publication}' skill-page.json CURSOR=$(jq -r '.nextCursor // empty' skill-page.json) [[ -n "$CURSOR" ]] || break done @@ -115,7 +114,7 @@ while true; do if [[ -n "$CURSOR" ]]; then PAGE_ARGS+=(--data-urlencode "cursor=$CURSOR"); fi curl --fail-with-body --silent --show-error --get "$PLAYBOOK_API/skills/$SKILL_ID/versions" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" "${PAGE_ARGS[@]}" > skill-versions.json - jq '.versions[] | {version, contentDigest, content}' skill-versions.json + jq '.items[] | {version, contentDigest, content}' skill-versions.json CURSOR=$(jq -r '.nextCursor // empty' skill-versions.json) [[ -n "$CURSOR" ]] || break done diff --git a/local_examples/iris/playbooks/skills/skills_delete.sh b/local_examples/iris/playbooks/skills/skills_delete.sh index ead76f7f24..80eb89fd1d 100644 --- a/local_examples/iris/playbooks/skills/skills_delete.sh +++ b/local_examples/iris/playbooks/skills/skills_delete.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . diff --git a/local_examples/iris/playbooks/skills/skills_withdraw.sh b/local_examples/iris/playbooks/skills/skills_withdraw.sh index 760e209084..b1ad9c7215 100644 --- a/local_examples/iris/playbooks/skills/skills_withdraw.sh +++ b/local_examples/iris/playbooks/skills/skills_withdraw.sh @@ -3,7 +3,7 @@ set -euo pipefail # HIDE_START set -euo pipefail -PLAYBOOK_API="${PLAYBOOK_URL%/}/v1/playbooks/$PLAYBOOK_ID" +PLAYBOOK_API="${PLAYBOOK_URL%/}/iris/data/v1/agent-playbooks/playbooks/$PLAYBOOK_ID" curl --fail-with-body --silent --show-error \ "$PLAYBOOK_API/health" \ -H "Authorization: Bearer $PLAYBOOK_API_KEY" | jq . From 52519be851c3ea6eec9f7a81f975590bedbe5f66 Mon Sep 17 00:00:00 2001 From: Robert Shelton Date: Fri, 30 Oct 2026 08:40:05 -0400 Subject: [PATCH 3/4] Iris docs: move the self-managed Agent Memory examples to the unified API Control-plane calls use /iris/v1/agent-memory (stores, detectors, memory-types, extractors, ingestion-hooks) with upper-case enums and 412 revision conflicts; data-plane calls use /iris/data/v1/agent-memory/stores/{storeId}, sessions, memories, ownerId/cursor/nextCursor, namespaceId, memoryId and query. Co-Authored-By: Claude Opus 5.5 --- .../iris/agent-memory/self-managed/_index.md | 12 +- .../agent-memory/self-managed/api-examples.md | 111 +++++++++--------- .../self-managed/authentication.md | 8 +- .../iris/agent-memory/self-managed/deploy.md | 12 +- 4 files changed, 74 insertions(+), 69 deletions(-) diff --git a/content/operate/iris/agent-memory/self-managed/_index.md b/content/operate/iris/agent-memory/self-managed/_index.md index 1fd40fa3df..fc9196351f 100644 --- a/content/operate/iris/agent-memory/self-managed/_index.md +++ b/content/operate/iris/agent-memory/self-managed/_index.md @@ -77,13 +77,13 @@ actions the key can access. | API surface | Endpoint prefix | Purpose | | --- | --- | --- | -| Session memory | `/v1/stores/{storeId}/session-memory` | Ordered conversation events, session metadata, and session lifecycle operations. | -| Long-term memory | `/v1/stores/{storeId}/long-term-memory` | Searchable facts, preferences, summaries, and custom memory records. | -| Namespaces | `/v1/stores/{storeId}/namespaces` | Namespace resources within a store. | -| Model Context Protocol (MCP) | `/v1/stores/{storeId}/mcp` | The MCP streamable-HTTP endpoint for a store. | -| Store health | `/v1/stores/{storeId}/health` | Read-only health for store-scoped features. | +| Session memory | `/iris/data/v1/agent-memory/stores/{storeId}/sessions` | Ordered conversation events, session metadata, and session lifecycle operations. | +| Long-term memory | `/iris/data/v1/agent-memory/stores/{storeId}/memories` | Searchable facts, preferences, summaries, and custom memory records. | +| Namespaces | `/iris/data/v1/agent-memory/stores/{storeId}/namespaces` | Namespace resources within a store. | +| Model Context Protocol (MCP) | `/iris/data/v1/agent-memory/stores/{storeId}/mcp` | The MCP streamable-HTTP endpoint for a store. | +| Store health | `/iris/data/v1/agent-memory/stores/{storeId}/health` | Read-only health for store-scoped features. | | Service health | `/health/liveness`, `/health/readiness` | Process liveness and readiness to serve requests; neither requires an agent key. | -| Control Plane | `/v1/stores`, `/v1/detectors` | Self-managed administration for stores, and the catalog of built-in sensitive-data detectors. | +| Control Plane | `/iris/v1/agent-memory/stores`, `/iris/v1/agent-memory/detectors` | Self-managed administration for stores, and the catalog of built-in sensitive-data detectors. | | Identity Service | `/v1/api-keys` | Self-managed administration for agent keys. | Session memory keeps conversation continuity within a session. Long-term memory diff --git a/content/operate/iris/agent-memory/self-managed/api-examples.md b/content/operate/iris/agent-memory/self-managed/api-examples.md index 84e35ceb0a..1db3e8012d 100644 --- a/content/operate/iris/agent-memory/self-managed/api-examples.md +++ b/content/operate/iris/agent-memory/self-managed/api-examples.md @@ -35,33 +35,38 @@ RAM_ADMIN_TOKEN="" List stores: ```bash -curl -sS "$CP_URL/v1/stores" \ +curl -sS "$CP_URL/iris/v1/agent-memory/stores" \ -H "Authorization: Bearer $RAM_ADMIN_TOKEN" ``` Create a store: ```bash -curl -sS -X POST "$CP_URL/v1/stores" \ +curl -sS -X POST "$CP_URL/iris/v1/agent-memory/stores" \ -H "Authorization: Bearer $RAM_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ - "name": "my-store" + "name": "my-store", + "database": { "databaseId": "" } }' ``` -Response: + + +The response is the full store record. It includes these fields, among others: ```json { - "storeId": "" + "storeId": "", + "name": "my-store", + "state": "" } ``` List the built-in sensitive-data detectors a store may select: ```bash -curl -sS "$CP_URL/v1/detectors" \ +curl -sS "$CP_URL/iris/v1/agent-memory/detectors" \ -H "Authorization: Bearer $RAM_ADMIN_TOKEN" ``` @@ -70,7 +75,7 @@ Response: ```json { "catalogVersion": "1.0.0", - "detectors": [ + "items": [ { "id": "credit-card", "name": "Credit card number", @@ -85,7 +90,7 @@ Read detector IDs from this endpoint rather than copying them from documentation Create a store with sensitive-data exclusions: ```bash -curl -sS -X POST "$CP_URL/v1/stores" \ +curl -sS -X POST "$CP_URL/iris/v1/agent-memory/stores" \ -H "Authorization: Bearer $RAM_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -95,8 +100,8 @@ curl -sS -X POST "$CP_URL/v1/stores" \ "builtInDetectors": { "enabled": true, "detectors": [ - { "id": "credit-card", "enabled": true, "action": "drop" }, - { "id": "ip-address", "enabled": true, "action": "redact" } + { "id": "credit-card", "enabled": true, "action": "DROP" }, + { "id": "ip-address", "enabled": true, "action": "REDACT" } ] }, "customDetectors": { @@ -105,9 +110,9 @@ curl -sS -X POST "$CP_URL/v1/stores" \ { "name": "internal-case-reference", "enabled": true, - "action": "redact", + "action": "REDACT", "matcher": { - "kind": "regex", + "kind": "REGEX", "regex": { "pattern": "CASE-REF-[0-9]{6}" } } } @@ -127,13 +132,13 @@ Exclusions fields: | ----- | ----- | | `enabled` | Required. Gates all three mechanisms. Turning it off stops enforcement without discarding what you configured. | | `builtInDetectors.enabled` | Required. | -| `builtInDetectors.detectors[].id` | Required. A detector ID from `/v1/detectors`. | +| `builtInDetectors.detectors[].id` | Required. A detector ID from `/iris/v1/agent-memory/detectors`. | | `customDetectors.enabled` | Required. | | `customDetectors.detectors[].name` | Required. 1-64 characters, starting with a letter, followed by letters, digits, underscores, or dashes. Unique within the store, and not a built-in detector ID. | | `detectors[].enabled` | Required on every built-in and custom detector. | -| `matcher.kind` | Required. Use `regex`. | -| `matcher.regex.pattern` | Required when `kind` is `regex`. 1-512 characters, using [RE2 syntax](https://github.com/google/re2/wiki/Syntax), so lookaround is unavailable. Rejected if it does not compile, or if it can match without consuming text. | -| `action` | Optional on any detector. Use `redact` to replace the matched text or `drop` to discard the memory. Defaults to `redact`. | +| `matcher.kind` | Required. Use `REGEX`. | +| `matcher.regex.pattern` | Required when `kind` is `REGEX`. 1-512 characters, using [RE2 syntax](https://github.com/google/re2/wiki/Syntax), so lookaround is unavailable. Rejected if it does not compile, or if it can match without consuming text. | +| `action` | Optional on any detector. Use `REDACT` to replace the matched text or `DROP` to discard the memory. Defaults to `REDACT`. | | `semantic.enabled` | Required. | | `semantic.prompt` | Required when `semantic.enabled` is `true`. Up to 2,000 characters. | @@ -150,7 +155,7 @@ The same package supplies two independently configured clients: | `AgentMemoryService` | Manage stores and extractors. Supply the store ID on each call. | Control Plane URL and operator `token`. | | `AgentMemory` | Read and write memory within the store selected by the constructor. | Data Plane URL, Store ID, and application credential. | -Use the self-managed Control Plane admin token or supported operator token with `AgentMemoryService`. Its SDK uses `/v2/memory` routes; the self-managed `/v1` admin API remains available. The SDK does not derive a Data Plane URL or credential from a Control Plane response. +Use the self-managed Control Plane admin token or supported operator token with `AgentMemoryService`. Its SDK and the self-managed admin REST API both use `/iris/v1/agent-memory` routes. The SDK does not derive a Data Plane URL or credential from a Control Plane response. Set `AGENT_MEMORY_CONTROL_PLANE_URL` and `AGENT_MEMORY_SERVICE_TOKEN` separately from `AGENT_MEMORY_URL`, `STORE_ID`, and `API_KEY`. These examples read the store and check Data Plane health: @@ -210,7 +215,7 @@ main().catch((error) => { If omitted, the Control Plane token is read from `AGENT_MEMORY_SERVICE_TOKEN`; it does not fall back to the Data Plane key. Python service models, errors, and retry helpers use `redis_agent_memory.controlplane`; Data Plane imports remain separate. Use each client's corresponding error classes. -Store and extractor management, detectors, and memory-type reference data have Cloud and self-managed API implementations. The generated client also includes Cloud-only account database, end user license agreement (EULA), network, store-model, metrics, flush, and empty-store operations; those return `404` on-prem. The current Cloud Control Plane does not accept a programmatic credential for this SDK. Use the Cloud console for Cloud service setup rather than sending a Data Plane key or assuming a console session is a service token. +Store and extractor management, detectors, and memory-type reference data have Cloud and self-managed API implementations. The generated client also includes Cloud-only account database, end user license agreement (EULA), network, store-model, metrics, flush, and empty-store operations; those return `404` on-prem. The current Cloud Control Plane does not accept a programmatic credential for this SDK. Use the Cloud console for Cloud service setup rather than sending a Data Plane key or assuming a console session is a service token. See [Create an extractor](#create-an-extractor) for extractor administration and the [self-managed Control Plane reference](/content/operate/iris/agent-memory/self-managed/control-plane-api-reference.md) for the admin REST API. Webhook-policy configuration uses the admin REST API; it is not a method on the current service SDK. @@ -221,16 +226,16 @@ For model and processing settings, see [Configure document ingestion](/content/o First register a custom memory type on the store. For a new `document_fact` type, run this once: ```sh -curl --fail-with-body --silent --show-error --request PATCH \ +curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $AGENT_MEMORY_SERVICE_TOKEN" \ --header 'Content-Type: application/json' \ - --data '{"addCustomMemoryTypes":[{"name":"document_fact","description":"Useful facts extracted from documents"}]}' \ - "$AGENT_MEMORY_CONTROL_PLANE_URL/v2/memory/stores/$STORE_ID" | jq + --data '{"name":"document_fact","description":"Useful facts extracted from documents"}' \ + "$AGENT_MEMORY_CONTROL_PLANE_URL/iris/v1/agent-memory/stores/$STORE_ID/memory-types" | jq ``` -Use an existing registered type instead if it already has the fields you need. Existing types cannot be redefined by adding them again. +Use an existing registered type instead if it already has the fields you need. Existing types cannot be redefined by adding them again; a duplicate name returns `409`. -Create an extractor with `source: documents` and `strategy: custom`. Save its returned `id` as `EXTRACTOR_ID`: +Create an extractor with `source: DOCUMENTS` and `strategy: CUSTOM`. Save its returned `extractorId` as `EXTRACTOR_ID`: {{< multitabs id="document-extractor" tab1="Python" tab2="TypeScript" tab3="curl" >}} @@ -287,15 +292,15 @@ main().catch((error) => { console.error(error instanceof Error ? error.message : curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $AGENT_MEMORY_SERVICE_TOKEN" \ --header 'Content-Type: application/json' \ - --data '{"name":"Travel guide facts","memoryType":"document_fact","source":"documents","strategy":"custom","prompt":"Extract useful travel facts. Keep each fact in one memory."}' \ - "$AGENT_MEMORY_CONTROL_PLANE_URL/v2/memory/stores/$STORE_ID/extractors" | jq + --data '{"name":"Travel guide facts","memoryType":"document_fact","source":"DOCUMENTS","strategy":"CUSTOM","prompt":"Extract useful travel facts. Keep each fact in one memory."}' \ + "$AGENT_MEMORY_CONTROL_PLANE_URL/iris/v1/agent-memory/stores/$STORE_ID/extractors" | jq ``` {{< /multitabs >}} Set `destinationNamespaceId` when creating an extractor to place its output in one namespace in the same store. Use a stable namespace ID, not a display name. Personal destinations must be compatible with the document owner; shared placement does not make the original document accessible to every reader of the extracted memories. -List or read extractors before editing them. Updates and removal require the current `expectedRevision`; a stale revision returns `409`. An update can change the name, prompt, enabled flag, or destination. An empty destination clears it; omission keeps it. Accepted ingestions retain their extractor snapshot, so a later edit does not change an existing run. +List or read extractors before editing them. Updates and removal require the current `expectedRevision`; a stale revision returns `412`. An update can change the name, prompt, enabled flag, or destination. An empty destination clears it; omission keeps it. Accepted ingestions retain their extractor snapshot, so a later edit does not change an existing run. After setup, applications can [submit and track documents](/content/develop/ai/context-engine/agent-memory/memory-etl.md#submit-and-track-a-document) with their Data Plane credentials. @@ -308,10 +313,10 @@ A policy PUT replaces the whole policy. Include every phase you want to retain; ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $AGENT_MEMORY_SERVICE_TOKEN" \ - "$AGENT_MEMORY_CONTROL_PLANE_URL/v1/stores/$STORE_ID/ingestion-hooks" > hook-config.json + "$AGENT_MEMORY_CONTROL_PLANE_URL/iris/v1/agent-memory/stores/$STORE_ID/ingestion-hooks" > hook-config.json ``` -A new store starts at revision 0. Generate separate 32-byte signing keys for the two phases, then configure them with delivery still disabled: +A new store starts at revision `0`. Generate separate 32-byte signing keys for the two phases, then configure them with delivery still disabled: ```sh export HOOK_INPUT_KEY="$(openssl rand -base64 32)" @@ -322,7 +327,7 @@ jq --arg url "$HOOK_URL" \ hook-config.json | curl --fail-with-body --silent --show-error --request PUT \ --header "Authorization: Bearer $AGENT_MEMORY_SERVICE_TOKEN" \ --header 'Content-Type: application/json' --data @- \ - "$AGENT_MEMORY_CONTROL_PLANE_URL/v1/stores/$STORE_ID/ingestion-hooks" > hook-config-new.json + "$AGENT_MEMORY_CONTROL_PLANE_URL/iris/v1/agent-memory/stores/$STORE_ID/ingestion-hooks" > hook-config-new.json ``` The response returns each phase's `keyId` and `signingKeyConfigured`, never its key. Supply those IDs and original keys to the [receiver example](/content/develop/ai/context-engine/agent-memory/ingestion-webhooks.md#verify-callbacks-and-return-decisions) through `HOOK_KEYS_JSON`: @@ -338,10 +343,10 @@ jq '{expectedRevision:.revision,enabled:true,beforeInput:{url:.beforeInput.url,p hook-config-new.json | curl --fail-with-body --silent --show-error --request PUT \ --header "Authorization: Bearer $AGENT_MEMORY_SERVICE_TOKEN" \ --header 'Content-Type: application/json' --data @- \ - "$AGENT_MEMORY_CONTROL_PLANE_URL/v1/stores/$STORE_ID/ingestion-hooks" | jq + "$AGENT_MEMORY_CONTROL_PLANE_URL/iris/v1/agent-memory/stores/$STORE_ID/ingestion-hooks" | jq ``` -A stale `expectedRevision` returns `409`. To rotate a key, supply a new `signingKey` and load its returned ID into the receiver. Retain the previous receiver key for 24 hours: pending work keeps its original endpoint and key version. Keep the previous endpoint reachable while that work completes; delivery does not follow redirects. Policy changes affect new work; they do not rewrite saved decisions or a pending run's policy. +A stale `expectedRevision` returns `412`. To rotate a key, supply a new `signingKey` and load its returned ID into the receiver. Retain the previous receiver key for 24 hours: pending work keeps its original endpoint and key version. Keep the previous endpoint reachable while that work completes; delivery does not follow redirects. Policy changes affect new work; they do not rewrite saved decisions or a pending run's policy. ## Identity Service API examples @@ -481,7 +486,7 @@ With ownership enforcement enabled, [configure delegation](/content/operate/iris ### Write a session event ```bash -curl -sS -X POST "$DP_URL/v1/stores/$STORE_ID/session-memory/events" \ +curl -sS -X POST "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" \ -H "Content-Type: application/json" \ @@ -506,12 +511,12 @@ Request body fields: | `role` | Required. Use `USER`, `ASSISTANT`, or `SYSTEM`. | | `content` | Required. For text, use a content object such as `{"text": "..."}`. | | `createdAt` | Required. Use an RFC 3339 timestamp, for example `2026-06-25T18:00:00Z`. | -| `sessionId` | Optional. If omitted, Redis Agent Memory generates one. | +| `sessionId` | Optional. If omitted, Redis Agent Memory generates one. If the session already exists, the request returns `409`; append later events with `POST /iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}/events`. | ### Read session memory ```bash -curl -sS "$DP_URL/v1/stores/$STORE_ID/session-memory/session-001" \ +curl -sS "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/session-001" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" ``` @@ -521,48 +526,46 @@ curl -sS "$DP_URL/v1/stores/$STORE_ID/session-memory/session-001" \ List sessions for a specific owner: ```bash -curl -sS --get "$DP_URL/v1/stores/$STORE_ID/session-memory" \ +curl -sS --get "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" \ - --data-urlencode "filterOwnerId=$OWNER_ID" + --data-urlencode "ownerId=$OWNER_ID" ``` List all sessions the caller can access: ```bash -curl -sS "$DP_URL/v1/stores/$STORE_ID/session-memory?includeAll=true" \ +curl -sS "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions?includeAll=true" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" ``` -`filterOwnerId` and `includeAll` are mutually exclusive. +`ownerId` and `includeAll` are mutually exclusive. -The `/session-memory` list returns session IDs. To get session rows ordered by -recent activity, use `/sessions`: +To get session rows ordered by recent activity, add sort options: ```bash -curl -sS --get "$DP_URL/v1/stores/$STORE_ID/sessions" \ +curl -sS --get "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" \ - --data-urlencode "filterOwnerId=$OWNER_ID" \ + --data-urlencode "ownerId=$OWNER_ID" \ --data-urlencode 'sortBy=updatedAt' \ - --data-urlencode 'sortOrder=desc' \ + --data-urlencode 'sortOrder=DESC' \ --data-urlencode 'limit=20' ``` Each row includes `sessionId` and, when known, `ownerId`, `createdAt`, -`updatedAt`, and `namespaceRef`. Older sessions can have no owner or timestamps. +`updatedAt`, and `namespaceId`. Older sessions can have no owner or timestamps. The default order is `updatedAt` descending. You can also sort by `sessionId` -or `createdAt`, each in ascending or descending order. Send `nextPageToken` as -`pageToken` with the same filters and sort options to fetch the next page. -Both routes use the same filter and authorization rules. +or `createdAt`, each in ascending (`ASC`) or descending (`DESC`) order. Send `nextCursor` as +`cursor` with the same filters and sort options to fetch the next page. ### Create long-term memories directly Create a personal namespace for the user's preferences and save its ID. Run this once, then reuse the ID for later writes: ```bash -NAMESPACE_ID=$(curl --fail-with-body -sS -X POST "$DP_URL/v1/stores/$STORE_ID/namespaces" \ +NAMESPACE_ID=$(curl --fail-with-body -sS -X POST "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespaces" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" \ -H "Content-Type: application/json" \ @@ -574,18 +577,18 @@ export NAMESPACE_ID After the request succeeds, place the memory in that namespace: ```bash -curl -sS -X POST "$DP_URL/v1/stores/$STORE_ID/long-term-memory" \ +curl -sS -X POST "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg ns "$NAMESPACE_ID" --arg owner "$OWNER_ID" '{ "memories": [ { - "id": "pref-email-updates", + "memoryId": "pref-email-updates", "text": "User prefers email updates.", "memoryType": "semantic", "ownerId": $owner, - "namespaceRef": {"namespaceId": $ns}, + "namespaceId": $ns, "topics": ["communications"] } ] @@ -599,14 +602,14 @@ See [organize memories with namespaces]({{< relref "/develop/ai/context-engine/a Filter by the namespace ID to recall preferences from that namespace: ```bash -curl -sS -X POST "$DP_URL/v1/stores/$STORE_ID/long-term-memory/search" \ +curl -sS -X POST "$DP_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories/search" \ -H "Authorization: Bearer $RAM_AGENT_KEY" \ -H "X-Iris-User-Token: ${USER_TOKEN:-}" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg ns "$NAMESPACE_ID" --arg owner "$OWNER_ID" '{ - "text": "How should we contact this user?", + "query": "How should we contact this user?", "filter": { - "namespaceRef": {"eq": $ns}, + "namespaceId": {"eq": $ns}, "ownerId": { "eq": $owner } diff --git a/content/operate/iris/agent-memory/self-managed/authentication.md b/content/operate/iris/agent-memory/self-managed/authentication.md index 0cf6a6a62b..75d3fe2c7d 100644 --- a/content/operate/iris/agent-memory/self-managed/authentication.md +++ b/content/operate/iris/agent-memory/self-managed/authentication.md @@ -24,7 +24,7 @@ grants. | Credential | Who presents it to whom | Secret / key | Auto-generated? | What it unlocks | | --- | --- | --- | --- | --- | -| Control Plane admin token | Operator → Control Plane (`:9100`) | `redis-agent-memory-controlplane-admin-token` / `token` | Yes (`controlplane.adminToken.autoGenerate`) | Store and extractor management through the `/v1` admin API and supported `/v2/memory` routes | +| Control Plane admin token | Operator → Control Plane (`:9100`) | `redis-agent-memory-controlplane-admin-token` / `token` | Yes (`controlplane.adminToken.autoGenerate`) | Store and extractor management through the `/iris/v1/agent-memory` admin API | | Control Plane internal token | Identity Service → Control Plane | `memory-internal-token` / `token` in the walkthrough | You provision it for both releases | Checking that the store in a grant exists. Set `controlplane.internalToken.existingSecret` on Memory and `productValidation.products.memory.credential.existingSecret` on Identity Service. | | Identity Service control token | Operator → Identity Service (`:9200`) | `ids-control-token` / `token` in the walkthrough | Supplied through `control.existingSecret` on Identity Service; that chart can also generate one | Creating, listing, updating, rotating and revoking agent keys | | Data Plane service credential | Data Plane → Identity Service | `memory-dp-credential` / `token` in the walkthrough | You provision it for both releases | Checking agent keys for `memory`. Set `identityService.credential.existingSecret` on Memory and register it in `runtime.serviceCredentials[]` on Identity Service. | @@ -282,8 +282,8 @@ main().catch((error) => { console.error(error instanceof Error ? error.message : curl --fail-with-body --silent --show-error --get \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: $USER_TOKEN" \ - --data-urlencode "filterOwnerId=$OWNER_ID" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/sessions" | jq + --data-urlencode "ownerId=$OWNER_ID" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions" | jq ``` {{< /multitabs >}} @@ -313,7 +313,7 @@ for session_id in "$OWN_SESSION_ID" "$OTHER_SESSION_ID" "$SHARED_SESSION_ID"; do curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: $USER_TOKEN" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/$session_id" + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$session_id" done ``` diff --git a/content/operate/iris/agent-memory/self-managed/deploy.md b/content/operate/iris/agent-memory/self-managed/deploy.md index fb1f117078..869baf3976 100644 --- a/content/operate/iris/agent-memory/self-managed/deploy.md +++ b/content/operate/iris/agent-memory/self-managed/deploy.md @@ -365,9 +365,9 @@ its row. The rows are checklist items CL-1 to CL-6. | CL-1 | `memory.license.license_path` is set | Server and worker pods `CrashLoopBackOff`; log: `initialize license enforcement: license validation failed; refusing to start: invalid license format` | Set `memory.license.license_path: /etc/redis-agent-memory/license` | | CL-2 | `memory.promote_session_memory.strategies.instruct.llm` is set | Worker pods `CrashLoopBackOff` (server stays Ready); log: `promote_session_memory: Strategies: strategies.instruct.llm is required.` | Add the `instruct.llm` block | | CL-3 | Each `llm.provider` names an `inference_providers` entry | Server and worker pods `CrashLoopBackOff`; log: `panic: config validation failed: promote_session_memory.strategies.instruct.llm: provider "" is not defined in inference_providers (defined: )` | Add `memory.inference_providers.` or fix the name | -| CL-4 | `memory.dataplane_client.base_url` is `http://redis-agent-memory:9000` | Pods Ready, but no memories appear; worker log: `getting session memory: Get "http://:9000/v1/stores//session-memory/..."` … `dial tcp: lookup ` (the rest depends on the cluster DNS) | Set `http://redis-agent-memory:9000` | +| CL-4 | `memory.dataplane_client.base_url` is `http://redis-agent-memory:9000` | Pods Ready, but no memories appear; worker log: `getting session memory: Get "http://:9000/iris/data/v1/agent-memory/stores//sessions/..."` … `dial tcp: lookup ` (the rest depends on the cluster DNS) | Set `http://redis-agent-memory:9000` | | CL-5 | Any overridden image tags exist in the chosen registry | Pods `ImagePullBackOff`, event: `Failed to pull image "redislabs/agent-memory:": … not found` | Use the published defaults or valid mirrored tags for each release | -| CL-6 | `auth.worker_identity` matches the worker (issuer, audience, subject with your namespace) | Pods Ready, but no memories appear; worker log: `memory-dataplane API error: status 401`; the Data Plane logs `401` on `GET /v1/stores//session-memory/` with no reason | Fix `issuer` from `/.well-known/openid-configuration` and the namespace in `subject`. The same symptom appears when the Data Plane cannot fetch the cluster JWKS, so also check [worker identity for your platform](#prepare-worker-identity-for-your-platform) | +| CL-6 | `auth.worker_identity` matches the worker (issuer, audience, subject with your namespace) | Pods Ready, but no memories appear; worker log: `memory-dataplane API error: status 401`; the Data Plane logs `401` on `GET /iris/data/v1/agent-memory/stores//sessions/` with no reason | Fix `issuer` from `/.well-known/openid-configuration` and the namespace in `subject`. The same symptom appears when the Data Plane cannot fetch the cluster JWKS, so also check [worker identity for your platform](#prepare-worker-identity-for-your-platform) | {{< /table-scrollable >}} ## 4. Install @@ -434,14 +434,16 @@ Use the Control Plane admin token: kubectl -n port-forward svc/redis-agent-memory-controlplane 9100:9100 RAM_ADMIN_TOKEN=$(kubectl -n get secret \ redis-agent-memory-controlplane-admin-token -o jsonpath='{.data.token}' | base64 -d) -curl -sS -X POST http://localhost:9100/v1/stores \ +curl -sS -X POST http://localhost:9100/iris/v1/agent-memory/stores \ -H "Authorization: Bearer $RAM_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ - -d '{"name": "my-store"}' + -d '{"name": "my-store", "database": {"databaseId": ""}}' ``` The response carries `storeId`. + + ## 7. Mint an agent key Use the Identity Service control token: @@ -473,7 +475,7 @@ The response's `token` is the agent key. It is shown only once. ## 8. Make one authenticated call ```bash -curl --fail-with-body -sS "http://localhost:9000/v1/stores//health" \ +curl --fail-with-body -sS "http://localhost:9000/iris/data/v1/agent-memory/stores//health" \ -H "Authorization: Bearer " ``` From 5e22c5a30ef4229d264f901d14bbdd4904d2ae23 Mon Sep 17 00:00:00 2001 From: Robert Shelton Date: Fri, 30 Oct 2026 08:44:24 -0400 Subject: [PATCH 4/4] Iris docs: move the Agent Memory developer REST examples to the unified API Data-plane calls use /iris/data/v1/agent-memory/stores/{storeId}: sessions (events appended at sessions/{sessionId}/events), memories, ingestion-hook-events, cursor/nextCursor with no total, ownerId and namespaceId filters, memoryId, viewId, search query and filter.op, upper-case enums, and document-ingestion outputs paged by cursor. One ListSessions operation replaces the two session lists. Co-Authored-By: Claude Opus 5.5 --- .../agent-memory/developer-guide.md | 12 ++-- .../agent-memory/ingestion-webhooks.md | 12 ++-- .../agent-memory/long-term-memory.md | 47 ++++++++------- .../context-engine/agent-memory/memory-etl.md | 55 +++++++++--------- .../agent-memory/namespaces/_index.md | 36 ++++++------ .../namespaces/namespace-routing.md | 28 ++++----- .../agent-memory/sessions/_index.md | 36 ++++++------ .../agent-memory/sessions/list-sessions.md | 23 ++++---- .../agent-memory/summary-views.md | 58 +++++++++---------- 9 files changed, 152 insertions(+), 155 deletions(-) diff --git a/content/develop/ai/context-engine/agent-memory/developer-guide.md b/content/develop/ai/context-engine/agent-memory/developer-guide.md index 964f1dd1b1..17a6100c4e 100644 --- a/content/develop/ai/context-engine/agent-memory/developer-guide.md +++ b/content/develop/ai/context-engine/agent-memory/developer-guide.md @@ -43,8 +43,8 @@ Some IDs come from your application; others come from Redis Agent Memory: | Session `ownerId` | The server copies it from the first event's `actorId`. | There is no separate `ownerId` input on a session-event request. Later actors do not change the session owner. | | Long-term memory `ownerId` | Your application for direct creation; extraction inherits the session owner. | Use the current user's stable ID for personal memories and owner filters. | | `eventId` | The server. | Save it from the event response if you need to refer to that event. | -| Long-term memory `id` | Your application for direct creation; the server during extraction. | Supply a stable record ID when creating a memory directly. | -| `namespaceId` | The server when it creates a namespace. | Save it and use it in `namespaceRef`. Supply the user's `ownerId` when creating a personal namespace. | +| Long-term memory `memoryId` | Your application for direct creation; the server during extraction. | Supply a stable record ID when creating a memory directly. | +| `namespaceId` | The server when it creates a namespace. | Save it and send it as `namespaceId`. Supply the user's `ownerId` when creating a personal namespace. | | Event `createdAt` | Your application. | Send when the message occurred; it is a required event input. | | Event `systemTimestamp` | The server. | Records when the event was stored. | | Memory `createdAt` and `updatedAt` | The server. | Use the returned timestamps when displaying or sorting memories. | @@ -57,13 +57,13 @@ For on-prem deployments, see [Server-side ownership enforcement](/content/operat Your application must decide which memories the user can access. Put these checks in trusted backend code before sending a request to Redis Agent Memory. Store access alone does not restrict a caller to one user's memories. Cloud store credentials also require these application checks; a Redis Cloud account user is not your application's end user. -* For personal searches, set the `ownerId` filter from the authenticated user's ID. For session listing, use `filterOwnerId`. A request from `user-42` must not be able to select `user-99` as its owner. +* For personal searches, set the `ownerId` filter from the authenticated user's ID. For session listing, use `ownerId`. A request from `user-42` must not be able to select `user-99` as its owner. * For shared memories, check which shared namespaces that user can access, then restrict the query to those namespace IDs. Do not add a personal owner filter to that shared query: it would hide shared memories written by other users. * For requests that retrieve or change a record by ID, check that the record belongs to the user or to a shared namespace they can access. These endpoints do not all accept an owner filter; a session or memory ID is not proof of permission. Use the authenticated user on every request to choose the owner filter or the permitted shared namespaces. Search filters limit results; they do not authenticate the user. For examples, see [Namespaces](/content/develop/ai/context-engine/agent-memory/namespaces/_index.md). -Keep mandatory owner restrictions separate from optional search conditions. Combining an owner and another filter with `filterOp: "any"` matches either condition; it does not require the owner to match. `includeAll` on a list request is also a selection option, not permission to enumerate a store. +Keep mandatory owner restrictions separate from optional search conditions. Combining an owner and another filter with `op: "ANY"` matches either condition; it does not require the owner to match. `includeAll` on a list request is also a selection option, not permission to enumerate a store. ## Build context for each agent turn @@ -183,7 +183,7 @@ The ingestion-hook `503` retry error and `422` stopped error also have distinct Create memories directly when your application already has information to store, such as a preference submitted through a form. Set the owner and a stable record ID. Creating an eligible record with the same ID again replaces it; access checks and protection for document-managed records still apply. Check the bulk response for per-record errors. Direct creation does not apply automatic extraction or sensitive-data exclusions. -See [Long-term memory]({{< relref "/develop/ai/context-engine/agent-memory/long-term-memory" >}}) for creation methods, search fields, retention, and extraction controls. +See [Long-term memory]({{< relref "/develop/ai/context-engine/agent-memory/memories" >}}) for creation methods, search fields, retention, and extraction controls. For unstructured documents, use [MemoryETL](/content/develop/ai/context-engine/agent-memory/memory-etl.md) to configure an extractor, submit a revision, and track its outputs. Source links let you trace extracted memories back to document or session inputs. @@ -203,7 +203,7 @@ See [Custom memory types]({{< relref "/develop/ai/context-engine/agent-memory/lo Namespaces are optional. Add them when your application needs to group conversations and memories by user, project, or team. -For example, create a personal `travel` namespace and save its `namespaceId`. Use that ID in `namespaceRef` when starting a session or creating long-term memories. You will also use this ID to search for memories in that namespace. Names and paths can change when you rename a namespace, but its ID stays the same. +For example, create a personal `travel` namespace and save its `namespaceId`. Use that ID as `namespaceId` when starting a session or creating long-term memories. You will also use this ID to search for memories in that namespace. Names and paths can change when you rename a namespace, but its ID stays the same. See [Namespaces]({{< relref "/develop/ai/context-engine/agent-memory/namespaces" >}}) for hierarchy, placement, search filters, and management. diff --git a/content/develop/ai/context-engine/agent-memory/ingestion-webhooks.md b/content/develop/ai/context-engine/agent-memory/ingestion-webhooks.md index 041725f35f..29e4bf8706 100644 --- a/content/develop/ai/context-engine/agent-memory/ingestion-webhooks.md +++ b/content/develop/ai/context-engine/agent-memory/ingestion-webhooks.md @@ -190,7 +190,7 @@ A document-input transform replaces its decoded text: | `session.append` | `actorId`, `role`, `content`, `createdAt`, and `metadata`. Session identity, owner, and placement stay fixed. | | `memory.create` | Editable text, type, session, owner, namespace placement, topics, and attributes. Record count, order, and IDs stay fixed. | -Do not supply both `namespace` and `namespaceRef`. Transformed records must still pass authorization and validation. +Use `namespaceId` for namespace placement. Transformed records must still pass authorization and validation. For `memory.create`, `session.builtin`, `session.custom`, and `document.chunk`, `decision: review` can decide each operation separately: @@ -221,12 +221,12 @@ export HOOK_TEST_MEMORY_ID="hook-test-$(openssl rand -hex 12)" export HOOK_TEST_REQUEST_ID="hook-request-$(openssl rand -hex 12)" jq -n --arg id "$HOOK_TEST_MEMORY_ID" --arg owner "$OWNER_ID" \ --arg key "$HOOK_TEST_REQUEST_ID" \ - '{idempotencyKey:$key,memories:[{id:$id,ownerId:$owner,text:"[reject] synthetic webhook test"}]}' > hook-test.json + '{idempotencyKey:$key,memories:[{memoryId:$id,ownerId:$owner,text:"[reject] synthetic webhook test"}]}' > hook-test.json curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: ${USER_TOKEN:-}" \ --header 'Content-Type: application/json' --data @hook-test.json \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories" | jq ``` With `memory.create` selected, inspect the per-record result and verify that the rejected record was not created. Use a new key for changed input; editing `hook-test.json` under the same key conflicts. @@ -325,7 +325,7 @@ if [ -n "${HOOK_EVENT_ID:-}" ]; then curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: ${USER_TOKEN:-}" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/ingestion-hooks/events/$HOOK_EVENT_ID" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/ingestion-hook-events/$HOOK_EVENT_ID" | jq else cursor='' while :; do @@ -333,8 +333,8 @@ else --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: ${USER_TOKEN:-}" \ --data-urlencode 'limit=20' --data-urlencode "cursor=$cursor" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/ingestion-hooks/events") || exit 1 - printf '%s\n' "$page" | jq .statuses + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/ingestion-hook-events") || exit 1 + printf '%s\n' "$page" | jq .items cursor=$(printf '%s' "$page" | jq -r '.nextCursor // empty') [ -n "$cursor" ] || break done diff --git a/content/develop/ai/context-engine/agent-memory/long-term-memory.md b/content/develop/ai/context-engine/agent-memory/long-term-memory.md index 1ec0fa2e63..c4bf196d68 100644 --- a/content/develop/ai/context-engine/agent-memory/long-term-memory.md +++ b/content/develop/ai/context-engine/agent-memory/long-term-memory.md @@ -28,18 +28,18 @@ See [memory configuration]({{< relref "/operate/iris/agent-memory/create-service ## Memory fields -When you create a memory directly, you must supply `id`, `text`, and `ownerId`. The server sets `createdAt` and `updatedAt`. During automatic extraction, the server creates the memory ID and content and copies the session owner into `ownerId`. Use that same stable user ID when querying personal memories; see [Authorize every memory request](/content/develop/ai/context-engine/agent-memory/developer-guide.md#authorize-every-memory-request). +When you create a memory directly, you must supply `memoryId`, `text`, and `ownerId`. The server sets `createdAt` and `updatedAt`. During automatic extraction, the server creates the memory ID and content and copies the session owner into `ownerId`. Use that same stable user ID when querying personal memories; see [Authorize every memory request](/content/develop/ai/context-engine/agent-memory/developer-guide.md#authorize-every-memory-request). A long-term memory record includes: | Field | Purpose | |:------|:--------| -| `id` | Unique identifier for the memory. | +| `memoryId` | Unique identifier for the memory. | | `text` | Memory content used for retrieval. | | `memoryType` | Built-in or custom memory type. | | `sessionId` | Session associated with the memory. | | `ownerId` | User or entity associated with the memory. | -| `namespaceRef` | Optional namespace ID and its current name and path. | +| `namespaceId` | Optional stable namespace ID. | | `attributes` | Custom memory fields and their values. | | `topics` | Topic tags used to categorize the memory. | | `createdAt` | Time the memory was created. | @@ -65,9 +65,9 @@ curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data @- \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/search" <}} @@ -112,30 +112,30 @@ curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg owner "$OWNER_ID" \ - '{filter: {ownerId: {eq: $owner}}, sortBy: "updatedAt", sortOrder: "desc", limit: 10}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/search" | jq + '{filter: {ownerId: {eq: $owner}}, sortBy: "updatedAt", sortOrder: "DESC", limit: 10}')" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories/search" | jq ``` {{< /multitabs >}} Use the client and identifiers from the [quickstart](/content/develop/ai/context-engine/agent-memory/quickstart.md). Add the Python snippet inside the `with` block and the TypeScript snippet inside `run`. -`sortBy` accepts `createdAt` or `updatedAt` only when `text` is absent. `sortOrder` accepts `asc` or `desc`, defaults to `desc`, and requires `sortBy`. Semantic searches remain ranked by similarity and cannot use these sort fields. `limit` accepts 1–100 and defaults to 10. Pass `nextPageToken` as `pageToken` with the same query to continue. +`sortBy` accepts `createdAt` or `updatedAt` only when `query` is absent. `sortOrder` accepts `ASC` or `DESC`, defaults to descending, and requires `sortBy`. Semantic searches remain ranked by similarity and cannot use these sort fields. `limit` accepts 1–100 and defaults to 50. Pass `nextCursor` as `cursor` with the same query to continue. -Top-level filters use `filterOp: "all"` (AND) by default; `"any"` uses OR. To restrict a query to a user, keep the owner condition mandatory. Do not use `"any"` with separate owner and namespace conditions when both must match. These retrieval filters do not replace application access checks. +Filter conditions use `filter.op: "ALL"` (AND) by default; `"ANY"` uses OR. To restrict a query to a user, keep the owner condition mandatory. Do not use `"ANY"` with separate owner and namespace conditions when both must match. These retrieval filters do not replace application access checks. -Set `filter.unnamespaced: true` to match records with neither the older `namespace` string label nor a namespace resource. It cannot be combined with `namespace` or `namespaceRef`, and remains mandatory even with `filterOp: "any"`. +Set `filter.unnamespaced: true` to match records with neither the older `namespace` string label nor a namespace resource. It cannot be combined with `namespaceId`, and remains mandatory even with `op: "ANY"`. [MemoryETL](/content/develop/ai/context-engine/agent-memory/memory-etl.md) outputs are included in search by default. Set top-level `excludeDocumentManaged: true` to omit them. Returned `documentManaged` records cannot be overwritten through generic memory creation or PATCH requests; use the document-ingestion workflow to manage their content. For custom fields, use `filter.attributes`, keyed by the field name, with the operators described in [`AttributeFilterClause`](/content/develop/ai/context-engine/agent-memory/api-reference.md#operation/SearchLongTermMemory). Combine it with `memoryType` to select the registered custom type. -For example, this search request combines the owner, type, and dietary requirement with `filterOp: "all"`. A `list` clause requires every listed value to be present: +For example, this search request combines the owner, type, and dietary requirement with `op: "ALL"`. A `list` clause requires every listed value to be present: ```json { - "filterOp": "all", "filter": { + "op": "ALL", "ownerId": {"eq": ""}, "memoryType": {"eq": "trip_preference"}, "attributes": {"dietary_requirements": {"list": ["vegetarian"]}} @@ -215,8 +215,8 @@ curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg owner "$OWNER_ID" --arg now "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ - '{sessionId:"trip-preference-session",actorId:$owner,role:"USER",content:[{text:"I am visiting Tokyo and Kyoto next month. I am vegetarian."}],createdAt:$now}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/events" | jq + '{actorId:$owner,role:"USER",content:[{text:"I am visiting Tokyo and Kyoto next month. I am vegetarian."}],createdAt:$now}')" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/trip-preference-session/events" | jq ``` {{< /multitabs >}} @@ -262,9 +262,9 @@ curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data @- \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/search" <}} -REST returns `202 Accepted`; this confirms submission, not successful extraction. In the SDKs, the submission content is under `accepted.result`, while the status read returns `ingestion.status`. Output listing uses `offset` and returns `memoryIds`. +REST returns `202 Accepted`; this confirms submission, not successful extraction. In the SDKs, the submission content is under `accepted.result`, while the status read returns `ingestion.status`. Output listing returns memory IDs in `items`; pass `nextCursor` as `cursor` for the next page. ## Interpret results and recover | Processing state | Meaning and action | |:-----------------|:-------------------| -| `queued` or `running` | Keep polling the saved ingestion ID. Do not create another submission to check progress. | -| `succeeded` | Processing finished. Inspect `createdCount` and `filteredCount`; success can produce no memories. | -| `partial` | Some chunks completed before a failure. Inspect `error`, counts, and available output IDs. Earlier writes remain. | -| `failed` | Inspect `error` and available outputs. Do not assume that every prior write was rolled back. | +| `QUEUED` or `RUNNING` | Keep polling the saved ingestion ID. Do not create another submission to check progress. | +| `SUCCEEDED` | Processing finished. Inspect `createdCount` and `filteredCount`; success can produce no memories. | +| `PARTIAL` | Some chunks completed before a failure. Inspect `error`, counts, and available output IDs. Earlier writes remain. | +| `FAILED` | Inspect `error` and available outputs. Do not assume that every prior write was rolled back. | -`completedChunks`, `totalChunks`, `extractorId`, and `extractorRevision` help identify what ran. `cleanup` is independent: `pending`, `deleted`, or `failed` describes temporary source cleanup. A successful extraction with failed cleanup needs operator attention; it is not a reason to submit the document again. Extracted memories and provenance can remain after source bytes are deleted. +`completedChunks`, `totalChunks`, `extractorId`, and `extractorRevision` help identify what ran. `cleanup` is independent: `PENDING`, `DELETED`, or `FAILED` describes temporary source cleanup. A successful extraction with failed cleanup needs operator attention; it is not a reason to submit the document again. Extracted memories and provenance can remain after source bytes are deleted. Reuse the same idempotency key and original request after a timeout or lost submission response. Changing the input under the same key conflicts. Reusing an immutable document revision with different content also conflicts. Use a new revision for changed content; do not change the bytes merely to force a retry of an existing run. @@ -314,20 +313,20 @@ while :; do links=$(curl --fail-with-body --silent --show-error --get \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: ${USER_TOKEN:-}" \ - --data-urlencode 'limit=100' --data-urlencode "pageToken=$source_token" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/$MEMORY_ID/sources") || exit 1 + --data-urlencode 'limit=100' --data-urlencode "cursor=$source_token" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories/$MEMORY_ID/sources") || exit 1 printf '%s\n' "$links" | jq .items printf '%s' "$links" | jq -c '.items[]' | while IFS= read -r source; do source_id=$(printf '%s' "$source" | jq -r .sourceId) - evidence_token=$(printf '%s' "$source" | jq -r '.evidenceNextPageToken // empty') + evidence_token=$(printf '%s' "$source" | jq -r '.evidenceNextCursor // empty') while [ -n "$evidence_token" ]; do evidence=$(curl --fail-with-body --silent --show-error --get \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: ${USER_TOKEN:-}" \ - --data-urlencode 'limit=100' --data-urlencode "pageToken=$evidence_token" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/$MEMORY_ID/sources/$source_id/evidence") || exit 1 + --data-urlencode 'limit=100' --data-urlencode "cursor=$evidence_token" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories/$MEMORY_ID/sources/$source_id/evidence") || exit 1 printf '%s\n' "$evidence" | jq .source - evidence_token=$(printf '%s' "$evidence" | jq -r '.source.evidenceNextPageToken // empty') + evidence_token=$(printf '%s' "$evidence" | jq -r '.source.evidenceNextCursor // empty') done reverse_token='' while :; do @@ -335,14 +334,14 @@ while :; do --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: ${USER_TOKEN:-}" \ --data-urlencode "ownerId=$OWNER_ID" --data-urlencode 'limit=100' \ - --data-urlencode "pageToken=$reverse_token" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/sources/$source_id/memories") || exit 1 + --data-urlencode "cursor=$reverse_token" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sources/$source_id/memories") || exit 1 printf '%s\n' "$related" | jq .items - reverse_token=$(printf '%s' "$related" | jq -r '.nextPageToken // empty') + reverse_token=$(printf '%s' "$related" | jq -r '.nextCursor // empty') [ -n "$reverse_token" ] || break done done || exit 1 - source_token=$(printf '%s' "$links" | jq -r '.nextPageToken // empty') + source_token=$(printf '%s' "$links" | jq -r '.nextCursor // empty') [ -n "$source_token" ] || break done ``` @@ -351,6 +350,6 @@ done The evidence response wraps `source`; it does not return a top-level `items` list. The source object contains `evidence` for documents or `sessionEvidence` for sessions. Newer evidence can also include `evidenceId`, `schemaVersion`, `capturedAt`, and `producer`. Handle their absence on legacy data. `capturedAt` is when extraction input was prepared, not when the original event occurred. A retried delivery retains its evidence identity. -For reverse lookup, use `GET /v1/stores/{storeId}/sources/{sourceId}/memories` with `ownerId`, or the corresponding SDK method. Follow its `nextPageToken` independently. Keep every token with the exact query and endpoint that issued it. Tokens expire; restart a query when one is invalid, and URL-encode tokens in REST calls. +For reverse lookup, use `GET /iris/data/v1/agent-memory/stores/{storeId}/sources/{sourceId}/memories` with `ownerId`, or the corresponding SDK method. Follow its `nextCursor` independently. Keep every token with the exact query and endpoint that issued it. Tokens expire; restart a query when one is invalid, and URL-encode tokens in REST calls. A source link does not grant access to the original document, session, or another owner's memories. The service checks source and record access separately; sharing an extracted memory does not share the private document it came from. diff --git a/content/develop/ai/context-engine/agent-memory/namespaces/_index.md b/content/develop/ai/context-engine/agent-memory/namespaces/_index.md index 951f7c610e..5af9f55d08 100644 --- a/content/develop/ai/context-engine/agent-memory/namespaces/_index.md +++ b/content/develop/ai/context-engine/agent-memory/namespaces/_index.md @@ -13,7 +13,7 @@ weight: 13 Namespaces are optional. Use them to group memories for a project, team, or user. For example, a travel agent can keep a user's trip memories in a personal `travel` namespace. -Create the namespace before writing to it. The response contains a server-generated `namespaceId`. Save this ID and use it in `namespaceRef` on session events and long-term memory writes. You will also use this ID to search for memories in that namespace. Names and paths can change when you rename a namespace, but its ID stays the same. +Create the namespace before writing to it. The response contains a server-generated `namespaceId`. Save this ID and use it as `namespaceId` on session events and long-term memory writes. You will also use this ID to search for memories in that namespace. Names and paths can change when you rename a namespace, but its ID stays the same. ## Create a personal namespace @@ -92,12 +92,12 @@ NAMESPACE_ID=$(curl --fail-with-body --silent --show-error \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg owner "$OWNER_ID" \ '{name: "travel", scope: "PERSONAL", ownerId: $owner}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/namespaces" | jq -er '.namespace.namespaceId') + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespaces" | jq -er '.namespace.namespaceId') export NAMESPACE_ID printf '%s\n' "$NAMESPACE_ID" ``` -Continue only after the request succeeds and prints a namespace ID. Save that ID for later runs. Creating the same namespace again returns `409 Conflict`; use the existing namespace ID instead. If you lose the ID, list personal roots with `GET /v1/stores/{storeId}/namespaces?scope=PERSONAL&ownerId=`. +Continue only after the request succeeds and prints a namespace ID. Save that ID for later runs. Creating the same namespace again returns `409 Conflict`; use the existing namespace ID instead. If you lose the ID, list personal roots with `GET /iris/data/v1/agent-memory/stores/{storeId}/namespaces?scope=PERSONAL&ownerId=`. Start a new session with this namespace: @@ -106,8 +106,8 @@ curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg owner "$OWNER_ID" --arg ns "$NAMESPACE_ID" --arg now "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ - '{sessionId:"travel-planning-with-namespace",actorId:$owner,role:"USER",content:[{text:"I am visiting Tokyo and Kyoto next month."}],createdAt:$now,namespaceRef:{namespaceId:$ns}}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/events" | jq + '{actorId:$owner,role:"USER",content:[{text:"I am visiting Tokyo and Kyoto next month."}],createdAt:$now,namespaceId:$ns}')" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/travel-planning-with-namespace/events" | jq ``` {{< /multitabs >}} @@ -169,7 +169,7 @@ SHARED_NAMESPACE_ID=$(curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data '{"name":"team-travel","scope":"SHARED"}' \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/namespaces" | jq -er '.namespace.namespaceId') + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespaces" | jq -er '.namespace.namespaceId') export SHARED_NAMESPACE_ID printf '%s\n' "$SHARED_NAMESPACE_ID" ``` @@ -180,7 +180,7 @@ Continue after the request succeeds and prints a namespace ID. Reuse that ID for Creating the same root again returns `409 Conflict`. If you lose the ID, list root namespaces with `scope=SHARED` and find `team-travel`. -To add a conversation to this namespace, use a new session ID and set its first event's namespace reference to the shared ID. Use `namespace_ref=shared_namespace_ref` in Python, `namespaceRef: sharedNamespaceRef` in TypeScript, or `"namespaceRef": {"namespaceId": "$SHARED_NAMESPACE_ID"}` in curl. For direct long-term memory creation, set the reference on each record. Creating the namespace does not move existing memories into it. +To add a conversation to this namespace, use a new session ID and set its first event's namespace reference to the shared ID. Use `namespace_ref=shared_namespace_ref` in Python, `namespaceRef: sharedNamespaceRef` in TypeScript, or `"namespaceId": "$SHARED_NAMESPACE_ID"` in curl. For direct long-term memory creation, set the reference on each record. Creating the namespace does not move existing memories into it. ### Recall shared memories @@ -216,21 +216,21 @@ curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg ns "$SHARED_NAMESPACE_ID" \ - '{text: "What travel requirements has the team discussed?", filter: {namespaceRef: {eq: $ns}}, limit: 5}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/search" | jq + '{query: "What travel requirements has the team discussed?", filter: {namespaceId: {eq: $ns}}, limit: 5}')" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories/search" | jq ``` {{< /multitabs >}} -The namespace filter selects that exact namespace. To search its children too, list them and include their IDs with `filter.namespaceRef.in`. +The namespace filter selects that exact namespace. To search its children too, list them and include their IDs with `filter.namespaceId.in`. ## Place and retrieve memories -Pass `namespaceRef: {"namespaceId": ""}` when you start a session. The first event fixes the session namespace. Later events cannot add or change it. Memories extracted from the session use that namespace, so use a new session ID when adding a namespace to the quickstart example. +Pass `"namespaceId": ""` on the first event when you start a session. The first event fixes the session namespace. Later events cannot add or change it. Memories extracted from the session use that namespace, so use a new session ID when adding a namespace to the quickstart example. -For direct long-term memory creation, set `namespaceRef` on each record. To move existing records, use `move_long_term_memories` (Python), `moveLongTermMemories` (TypeScript), or `POST /v1/stores/{storeId}/long-term-memory/move` with their IDs and the destination `namespaceRef`. Check both `moved` and `errors` in the response before treating a batch as complete. +For direct long-term memory creation, set `namespaceId` on each record. To move existing records, use `move_long_term_memories` (Python), `moveLongTermMemories` (TypeScript), or `POST /iris/data/v1/agent-memory/stores/{storeId}/memories/move` with their IDs and the destination `namespaceId`. Check both `moved` and `errors` in the response before treating a batch as complete. -Search with `filter.namespaceRef.eq` for one namespace or `filter.namespaceRef.in` for several IDs. These filters match exact namespace IDs; they do not expand a parent into its descendants. List the children and include their IDs when you need to search several levels of a hierarchy. Keep the `ownerId` filter when recalling one user's memories. +Search with `filter.namespaceId.eq` for one namespace or `filter.namespaceId.in` for several IDs. These filters match exact namespace IDs; they do not expand a parent into its descendants. List the children and include their IDs when you need to search several levels of a hierarchy. Keep the `ownerId` filter when recalling one user's memories. Your application must check that the current user can access each namespace before querying it. In on-prem deployments with ownership enforcement enabled, personal namespace access follows the root owner's authenticated user ID. Shared namespaces are accessible to callers with the required store permission. If a shared namespace is only for one team, enforce that rule in your application or use separate stores and grants. See [Authorize every memory request](/content/develop/ai/context-engine/agent-memory/developer-guide.md#authorize-every-memory-request). @@ -245,7 +245,7 @@ Choose a root scope when you create a namespace: Create a child with `name` and `parentId`. You can also create a hierarchy with `path`, such as `travel/japan`, and the root scope. Supply `ownerId` for a personal path. Missing path segments are created as needed. Do not combine `path` with `name` or `parentId`. -To create a child, pass this request body to `create_namespace` (Python), `createNamespace` (TypeScript), or `POST /v1/stores/{storeId}/namespaces`: +To create a child, pass this request body to `create_namespace` (Python), `createNamespace` (TypeScript), or `POST /iris/data/v1/agent-memory/stores/{storeId}/namespaces`: ```json {"name": "japan", "parentId": ""} @@ -265,7 +265,7 @@ For runnable examples, see [Create a personal namespace]({{< relref "/develop/ai | Operation | Behavior | |:----------|:---------| -| List | List roots, or pass `parentId` to list direct children. Sort by `id`, `name`, `createdAt`, or `updatedAt` with `sortBy`; `sortOrder` accepts `asc` or `desc`. Defaults are `id` and `asc`. Follow `nextPageToken` with the same filters and sort options. | +| List | List roots, or pass `parentId` to list direct children. Sort by `id`, `name`, `createdAt`, or `updatedAt` with `sortBy`; `sortOrder` accepts `ASC` or `DESC`. Defaults are `id` and `asc`. Follow `nextCursor` with the same filters and sort options. | | Get | Retrieve the current name, path, scope, and state by ID. | | Rename | Update `name`; continue using the same ID for placement and retrieval. | | Archive | Set `state` to `ARCHIVED` to stop new children and placements. You cannot unarchive a namespace. | @@ -308,8 +308,8 @@ Use the client from the [quickstart](/content/develop/ai/context-engine/agent-me curl --fail-with-body --silent --show-error --get \ --header "Authorization: Bearer $API_KEY" \ --data-urlencode 'scope=SHARED' --data-urlencode 'limit=20' \ - --data-urlencode 'sortBy=name' --data-urlencode 'sortOrder=asc' \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/namespaces" | jq + --data-urlencode 'sortBy=name' --data-urlencode 'sortOrder=ASC' \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespaces" | jq ``` {{< /multitabs >}} @@ -318,4 +318,4 @@ Add the Python snippet inside the `with` block and the TypeScript snippet inside ## Route and admit shared memories -An explicit namespace destination must pass its admission rules. Direct creation without a namespace stays unassigned. To route an existing shared memory, omit `namespaceRef` from a move request. Personal and unassigned memories are not candidates for automatic routing. See [Namespace routing](/content/develop/ai/context-engine/agent-memory/namespaces/namespace-routing.md) for policy setup, examples, and per-item errors. +An explicit namespace destination must pass its admission rules. Direct creation without a namespace stays unassigned. To route an existing shared memory, omit `namespaceId` from a move request. Personal and unassigned memories are not candidates for automatic routing. See [Namespace routing](/content/develop/ai/context-engine/agent-memory/namespaces/namespace-routing.md) for policy setup, examples, and per-item errors. diff --git a/content/develop/ai/context-engine/agent-memory/namespaces/namespace-routing.md b/content/develop/ai/context-engine/agent-memory/namespaces/namespace-routing.md index 8181664617..53d3c2a604 100644 --- a/content/develop/ai/context-engine/agent-memory/namespaces/namespace-routing.md +++ b/content/develop/ai/context-engine/agent-memory/namespaces/namespace-routing.md @@ -21,10 +21,10 @@ The policy applies to one store. It targets existing shared namespace resources, | Request | Behavior | |:--------|:---------| -| Create a memory with `namespaceRef` | Use that destination after admission checks. The service never chooses another destination. | -| Create a memory without `namespace` or `namespaceRef` | Create it without a namespace. Automatic routing does not place it in a shared namespace. | -| Move a memory with `namespaceRef` | Use that destination after admission checks. | -| Move a memory without `namespaceRef` | Evaluate automatic routing only if the memory is already in a shared namespace. | +| Create a memory with `namespaceId` | Use that destination after admission checks. The service never chooses another destination. | +| Create a memory without `namespaceId` | Create it without a namespace. Automatic routing does not place it in a shared namespace. | +| Move a memory with `namespaceId` | Use that destination after admission checks. | +| Move a memory without `namespaceId` | Evaluate automatic routing only if the memory is already in a shared namespace. | | Update a memory | Check the merged record against admission at its current destination. An update never chooses another destination. | An automatic move keeps the current placement and returns a per-item error if routing is disabled, no destination qualifies, or the memory is personal or has no namespace. Inspect both `moved` and `errors` in a move response. Bulk creation also reports failures per record in `errors`. An explicit move to an archived namespace returns `409 Conflict`. @@ -111,7 +111,7 @@ main().catch((error) => { console.error(error instanceof Error ? error.message : ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/namespace-routing" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespace-routing" | jq curl --fail-with-body --silent --show-error \ --request PUT \ @@ -119,10 +119,10 @@ curl --fail-with-body --silent --show-error \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg ns "$SHARED_NAMESPACE_ID" \ '{policy: {enabled: true, rules: [{id: "travel", enabled: true, - action: "accept", destination: {namespaceId: $ns}, strategies: [{ - kind: "matcher_spec", matcher: {kind: "regex", regex: {pattern: "(?i)travel"}} + action: "ACCEPT", destinationNamespaceId: $ns, strategies: [{ + kind: "MATCHER_SPEC", matcher: {kind: "REGEX", regex: {pattern: "(?i)travel"}} }]}]}}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/namespace-routing" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespace-routing" | jq ``` {{< /multitabs >}} @@ -131,9 +131,9 @@ curl --fail-with-body --silent --show-error \ In this example, `travel` is an accept rule with one strategy, a regex matcher. -An enabled `accept` rule selects a candidate destination. Accept rules run in list order. Every enabled `reject` rule for that destination applies, including rules later in the list. A matching reject vetoes the candidate. Automatic routing then tries another candidate; explicit placement fails rather than choosing another namespace. +An enabled `ACCEPT` rule selects a candidate destination. Accept rules run in list order. Every enabled `REJECT` rule for that destination applies, including rules later in the list. A matching reject vetoes the candidate. Automatic routing then tries another candidate; explicit placement fails rather than choosing another namespace. -Strategies within a rule run in list order; the first match fires the rule. An accept rule with no strategies always matches. A reject rule with no strategies never matches. Use `matcher_spec` with a `regex` matcher for text patterns, or `llm_prompt` with `llmPrompt` for a model-evaluated instruction. Each strategy must contain only the block for its declared `kind`. +Strategies within a rule run in list order; the first match fires the rule. An accept rule with no strategies always matches. A reject rule with no strategies never matches. Use `MATCHER_SPEC` with a `REGEX` matcher for text patterns, or `LLM_PROMPT` with `llmPrompt` for a model-evaluated instruction. Each strategy must contain only the block for its declared `kind`. A store without a saved policy returns an empty, disabled policy. Regular expressions use RE2 syntax. Lookaround, backreferences, invalid expressions, and patterns that can match empty text are not supported. A policy supports up to 32 rules and 8 strategies per rule. See [`PutNamespaceRouting`](/content/develop/ai/context-engine/agent-memory/api-reference.md#operation/PutNamespaceRouting) for validation and error responses. @@ -146,14 +146,14 @@ SOURCE_NAMESPACE_ID=$(curl --fail-with-body --silent --show-error --request POST --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data '{"name":"routing-source","scope":"SHARED"}' \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/namespaces" | jq -er '.namespace.namespaceId') || exit 1 + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/namespaces" | jq -er '.namespace.namespaceId') || exit 1 export MEMORY_ID='routing-travel-example' curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg id "$MEMORY_ID" --arg owner "$OWNER_ID" --arg ns "$SOURCE_NAMESPACE_ID" \ - '{memories:[{id:$id,ownerId:$owner,text:"Travel policy allows train tickets.",namespaceRef:{namespaceId:$ns}}]}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory" | jq + '{memories:[{memoryId:$id,ownerId:$owner,text:"Travel policy allows train tickets.",namespaceId:$ns}]}')" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories" | jq ``` Continue only if the namespace request succeeds and the memory response has no per-record errors. Run the move in the same shell, or pass the exported `MEMORY_ID` to your SDK process: @@ -184,7 +184,7 @@ curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg id "$MEMORY_ID" '{memoryIds: [$id]}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/long-term-memory/move" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/memories/move" | jq ``` {{< /multitabs >}} diff --git a/content/develop/ai/context-engine/agent-memory/sessions/_index.md b/content/develop/ai/context-engine/agent-memory/sessions/_index.md index b9e7e287b3..a6c0f4162b 100644 --- a/content/develop/ai/context-engine/agent-memory/sessions/_index.md +++ b/content/develop/ai/context-engine/agent-memory/sessions/_index.md @@ -19,14 +19,14 @@ This page covers adding events, retrieving a conversation, and finding session I ## Add session events -A session event represents one message from a user, assistant, or system. To add one, send `POST /v1/stores/{storeId}/session-memory/events`, or call `add_session_event` in Python or `addSessionEvent` in TypeScript. +A session event represents one message from a user, assistant, or system. To append one, send `POST /iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}/events`, which creates the session if it does not exist, or call `add_session_event` in Python or `addSessionEvent` in TypeScript. To start a session with a server-generated ID, send its first event to `POST /iris/data/v1/agent-memory/stores/{storeId}/sessions` instead. Redis Agent Memory adds the event ID and storage timestamp. The event fields are: | Field | Who supplies it | Purpose | |:------|:----------------|:--------| | `eventId` | Server-generated. | Identifies the event. | -| `sessionId` | Client-supplied, or server-generated when omitted. | Identifies the session that contains the event. | +| `sessionId` | Client-supplied in the path, or server-generated when you create a session without one. | Identifies the session that contains the event. | | `actorId` | Required from the client. | Identifies the user, agent, or other actor that produced the event. | | `role` | Required from the client. | Role of the message in the conversation. | | `content` | Required from the client. | Message content, including its text. | @@ -44,8 +44,8 @@ curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data "$(jq -n --arg session "$SESSION_ID" --arg owner "$OWNER_ID" --arg now "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ - '{sessionId:$session,actorId:$owner,role:"USER",content:[{text:"I am vegetarian."}],createdAt:$now}')" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/events" | jq + '{actorId:$owner,role:"USER",content:[{text:"I am vegetarian."}],createdAt:$now}')" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$SESSION_ID/events" | jq ``` Send each new message once, using the same session ID throughout the conversation. @@ -59,7 +59,7 @@ When the next message arrives, retrieve the session by its ID before calling the ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/$SESSION_ID" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$SESSION_ID" | jq ``` The `events` array contains the retained conversation messages. If older events have been summarized, the response also includes `summary.text`. Pass both to the model with the current user message. See [Build context for each agent turn]({{< relref "/develop/ai/context-engine/agent-memory/developer-guide#build-context-for-each-agent-turn" >}}) for an example. @@ -68,41 +68,41 @@ Your application must check that the current user can access this session before ## List sessions -To let a user reopen an earlier conversation, list their sessions and retrieve the selected session by ID. Use `GET /v1/stores/{storeId}/sessions`, `list_session_summaries` in Python, or `listSessionSummaries` in TypeScript. These rows do not contain events or generated summary text. See [List and sort sessions](/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md) for SDK examples and pagination. +To let a user reopen an earlier conversation, list their sessions and retrieve the selected session by ID. Use `GET /iris/data/v1/agent-memory/stores/{storeId}/sessions`, `list_sessions` in Python, or `listSessions` in TypeScript. These rows do not contain events or generated summary text. See [List and sort sessions](/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md) for SDK examples and pagination. -For session IDs only, use `GET /v1/stores/{storeId}/session-memory` with an owner or namespace filter. Reuse the curl connection values from the [quickstart]({{< relref "/develop/ai/context-engine/agent-memory/quickstart#save-the-connection-values" >}}). +Filter the list by owner or namespace. Reuse the curl connection values from the [quickstart]({{< relref "/develop/ai/context-engine/agent-memory/quickstart#save-the-connection-values" >}}). -For a user's personal conversations, set `filterOwnerId` to that user's authenticated ID. A namespace-only query is suitable for shared conversations only after your application checks access to that namespace. Reserve `includeAll=true` for callers your application authorizes to list the whole store. See [Authorize every memory request](/content/develop/ai/context-engine/agent-memory/developer-guide.md#authorize-every-memory-request). +For a user's personal conversations, set `ownerId` to that user's authenticated ID. A namespace-only query is suitable for shared conversations only after your application checks access to that namespace. Reserve `includeAll=true` for callers your application authorizes to list the whole store. See [Authorize every memory request](/content/develop/ai/context-engine/agent-memory/developer-guide.md#authorize-every-memory-request). To list sessions in one namespace, set `NAMESPACE_ID` to the stable ID returned when you [create a namespace]({{< relref "/develop/ai/context-engine/agent-memory/namespaces#create-a-personal-namespace" >}}): ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory?namespaceRef=$NAMESPACE_ID" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions?namespaceId=$NAMESPACE_ID" | jq ``` -`namespaceRef` matches the namespace ID exactly, including case. It excludes descendant namespaces, sessions with only the older `namespace` string label, and sessions without a namespace resource. +`namespaceId` matches the namespace ID exactly, including case. It excludes descendant namespaces, sessions with only the older `namespace` string label, and sessions without a namespace resource. -Add `filterOwnerId` to return sessions that match both the namespace and the owner: +Add `ownerId` to return sessions that match both the namespace and the owner: ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory?namespaceRef=$NAMESPACE_ID&filterOwnerId=$OWNER_ID" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions?namespaceId=$NAMESPACE_ID&ownerId=$OWNER_ID" | jq ``` -You can also use `filterOwnerId` alone. To list all sessions, omit both filters and set `includeAll=true`: +You can also use `ownerId` alone. To list all sessions, omit both filters and set `includeAll=true`: ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory?includeAll=true" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions?includeAll=true" | jq ``` Do not combine `includeAll=true` with either filter. A request without a filter must set `includeAll=true`. -The response contains session IDs in `items` and the number of matching sessions in `total`. If the response includes `nextPageToken`, pass it as `pageToken` with the same filters to fetch the next page. See the [List Sessions API reference]({{< relref "/develop/ai/context-engine/agent-memory/api-reference" >}}#operation/ListSessions) for pagination limits. +The response contains session rows in `items` and no total count. If the response includes `nextCursor`, pass it as `cursor` with the same filters to fetch the next page. See the [List Sessions API reference]({{< relref "/develop/ai/context-engine/agent-memory/api-reference" >}}#operation/ListSessions) for pagination limits. ## Configure session retention @@ -200,11 +200,11 @@ jq -cn --arg user "$OWNER_ID" '[ ] | .[]' | while IFS= read -r turn; do printf '%s' "$turn" | jq --arg session "$SESSION_ID" \ --arg now "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ - '{sessionId:$session,actorId:.actorId,role:.role,content:[{text:.text}],createdAt:$now}' | \ + '{actorId:.actorId,role:.role,content:[{text:.text}],createdAt:$now}' | \ curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' --data @- \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/events" || exit 1 + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$SESSION_ID/events" || exit 1 done ``` @@ -239,7 +239,7 @@ After a short wait, retrieve the session again: ```sh curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $API_KEY" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/session-memory/$SESSION_ID" | jq + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$SESSION_ID" | jq ``` {{< /multitabs >}} diff --git a/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md b/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md index d5eeb0363f..d2c0ffe0c1 100644 --- a/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md +++ b/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md @@ -13,24 +13,23 @@ aliases: - /develop/ai/context-engine/agent-memory/list-sessions/ --- -Use session listing to let a user reopen an earlier conversation. The session rows contain IDs and available owner, timestamp, and namespace metadata. They do not contain conversation events or summary text. Retrieve the selected session with `get_session_memory` (Python), `getSessionMemory` (TypeScript), or `GET /v1/stores/{storeId}/session-memory/{sessionId}` to build the agent's conversation context. +Use session listing to let a user reopen an earlier conversation. The session rows contain IDs and available owner, timestamp, and namespace metadata. They do not contain conversation events or summary text. Retrieve the selected session with `get_session_memory` (Python), `getSessionMemory` (TypeScript), or `GET /iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}` to build the agent's conversation context. ## Choose a listing operation | Result you need | REST endpoint | Python method | TypeScript method | |:----------------|:--------------|:--------------|:------------------| -| Session IDs | `GET /v1/stores/{storeId}/session-memory` | `list_sessions` | `listSessions` | -| Session rows with sorting | `GET /v1/stores/{storeId}/sessions` | `list_session_summaries` | `listSessionSummaries` | +| Session rows with sorting | `GET /iris/data/v1/agent-memory/stores/{storeId}/sessions` | `list_sessions` | `listSessions` | -The second method's name refers to metadata rows, not generated conversation summaries. Both operations return `items`, `total`, and an optional `nextPageToken`. +The operation returns `items` and an optional `nextCursor`. It does not return a total count. -For a user's personal conversations, set `filterOwnerId` to the user's authenticated ID. The session owner is the first event's `actorId`. Add `namespaceRef` to require an exact namespace ID as well. It does not include descendants, deprecated namespace labels, or sessions without a namespace resource. Owner and namespace matching is case-sensitive. +For a user's personal conversations, set `ownerId` to the user's authenticated ID. The session owner is the first event's `actorId`. Add `namespaceId` to require an exact namespace ID as well. It does not include descendants, deprecated namespace labels, or sessions without a namespace resource. Owner and namespace matching is case-sensitive. A request without filters must set `includeAll=true`. Do not combine `includeAll=true` with either filter. Authorize store-wide or shared namespace listing in your application before making the request. A filter selects records; it does not establish the caller's right to access them. ## Sort and paginate session rows -The default is `sortBy=updatedAt` and `sortOrder=desc`, so recent activity appears first. `sortBy` accepts `sessionId`, `createdAt`, or `updatedAt`. When omitted, `sortOrder` is `asc` for `sessionId` and `desc` for timestamps. `limit` accepts 1–1000 and defaults to 100. +The default is `sortBy=updatedAt` and `sortOrder=DESC`, so recent activity appears first. `sortBy` accepts `sessionId`, `createdAt`, or `updatedAt`. `sortOrder` accepts `ASC` or `DESC`. When omitted, it is ascending for `sessionId` and descending for timestamps. `limit` accepts 1–200 and defaults to 100. Install `redis-agent-memory` for Python or `@redis-iris/agent-memory` for TypeScript. Set `AGENT_MEMORY_URL`, `STORE_ID`, `API_KEY`, and `OWNER_ID` in your shell. See the [developer guide](/content/develop/ai/context-engine/agent-memory/developer-guide.md#connect-to-a-redis-agent-memory-service) for connection details. @@ -107,18 +106,18 @@ page_token='' while :; do page=$(curl --fail-with-body --silent --show-error --get \ --header "Authorization: Bearer $API_KEY" \ - --data-urlencode "filterOwnerId=$OWNER_ID" \ - --data-urlencode 'sortBy=updatedAt' --data-urlencode 'sortOrder=desc' \ - --data-urlencode 'limit=20' --data-urlencode "pageToken=$page_token" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/sessions") || break + --data-urlencode "ownerId=$OWNER_ID" \ + --data-urlencode 'sortBy=updatedAt' --data-urlencode 'sortOrder=DESC' \ + --data-urlencode 'limit=20' --data-urlencode "cursor=$page_token" \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions") || break printf '%s\n' "$page" | jq '.items' - page_token=$(printf '%s\n' "$page" | jq -r '.nextPageToken // empty') + page_token=$(printf '%s\n' "$page" | jq -r '.nextCursor // empty') [ -n "$page_token" ] || break done ``` {{< /multitabs >}} -Pass each returned `nextPageToken` as `pageToken`. Keep filters and sort options unchanged; the token is bound to them. Stop when the token is absent. The token is opaque, so URL-encode it in REST requests. Changing a filter or sort requires a new request without the old token. +Pass each returned `nextCursor` as `cursor`. Keep filters and sort options unchanged; the token is bound to them. Stop when the token is absent. The token is opaque, so URL-encode it in REST requests. Changing a filter or sort requires a new request without the old token. Sessions stored without owner or timestamp metadata can omit `ownerId`, `createdAt`, or `updatedAt`. Handle those missing values when rendering a conversation list. A row's timestamps describe session metadata; they do not promise that background extraction or summarization has completed. diff --git a/content/develop/ai/context-engine/agent-memory/summary-views.md b/content/develop/ai/context-engine/agent-memory/summary-views.md index 5028b1bd79..4976d683f4 100644 --- a/content/develop/ai/context-engine/agent-memory/summary-views.md +++ b/content/develop/ai/context-engine/agent-memory/summary-views.md @@ -15,7 +15,7 @@ A Summary View turns selected long-term memories into a reusable text or structu A **definition** specifies the sources, filters, grouping, output, and refresh policy. A **partition** is one materialized result for an exact combination of grouping values. An ungrouped definition has one result. Results are derived data; they do not enter long-term-memory search or replace the source records. -Summary Views differ from [session summarization](/content/develop/ai/context-engine/agent-memory/sessions/_index.md#configure-automatic-summarization), which compacts conversation events. The supported source is `long_term`. Document-managed MemoryETL records are excluded from Summary View sources. +Summary Views differ from [session summarization](/content/develop/ai/context-engine/agent-memory/sessions/_index.md#configure-automatic-summarization), which compacts conversation events. The supported source is `LONG_TERM`. Document-managed MemoryETL records are excluded from Summary View sources. ## Prepare the service and identity @@ -142,32 +142,32 @@ main().catch((error) => { console.error(error instanceof Error ? error.message : ```sh definition=$(jq -n --arg owner "$OWNER_ID" \ - '{name:"Travel profile",source:"long_term",groupBy:[],filter:{ownerId:{eq:$owner}},output:{format:"text",instructions:"Summarize travel preferences."},refreshPolicy:{mode:"manual"}}') + '{name:"Travel profile",source:"LONG_TERM",groupBy:[],filter:{ownerId:{eq:$owner}},output:{format:"TEXT",instructions:"Summarize travel preferences."},refreshPolicy:{mode:"MANUAL"}}') view=$(curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: $USER_TOKEN" \ --header 'Content-Type: application/json' --data "$definition" \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/summary-views") || exit 1 -VIEW_ID=$(printf '%s' "$view" | jq -er .id) || exit 1 + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/summary-views") || exit 1 +VIEW_ID=$(printf '%s' "$view" | jq -er .viewId) || exit 1 printf 'View ID: %s\n' "$VIEW_ID" curl --fail-with-body --silent --show-error --request POST \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: $USER_TOKEN" \ - --header 'Content-Type: application/json' --data '{"target":"full"}' \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/summary-views/$VIEW_ID/refresh" | jq + --header 'Content-Type: application/json' --data '{"target":"FULL"}' \ + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/summary-views/$VIEW_ID/refresh" | jq for attempt in $(seq 1 60); do result=$(curl --fail-with-body --silent --show-error --get \ --header "Authorization: Bearer $API_KEY" \ --header "X-Iris-User-Token: $USER_TOKEN" \ --data-urlencode 'includeSourceMemoryIds=true' \ - "$AGENT_MEMORY_URL/v1/stores/$STORE_ID/summary-views/$VIEW_ID/result") || exit 1 + "$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/summary-views/$VIEW_ID/result") || exit 1 state=$(printf '%s' "$result" | jq -r .status) case "$state" in - failed) printf '%s\n' "$result" | jq; exit 1 ;; - empty) printf 'No matching source memories.\n'; exit 0 ;; - ready) + FAILED) printf '%s\n' "$result" | jq; exit 1 ;; + EMPTY) printf 'No matching source memories.\n'; exit 0 ;; + READY) if printf '%s' "$result" | jq -e '.stale == false and .value != null' >/dev/null; then printf '%s\n' "$result" | jq exit 0 @@ -187,12 +187,12 @@ Text output uses `value.text`; structured output uses `value.data`. Python outpu | Status | Application behavior | |:-------|:---------------------| -| `cold` | No result is stored for this group. It may not have been generated yet, or it may have been evicted. | -| `pending` | Work is queued. Previous output may be withheld because its sources changed or became inaccessible. | -| `ready` | A value is available. Check `stale` and coverage fields. | -| `empty` | No sources match. There is no generated value. | -| `refreshing` | New work is running. A last good value can remain. | -| `failed` | Inspect `errorCode`. A last good value may remain, or `value` may be absent. | +| `COLD` | No result is stored for this group. It may not have been generated yet, or it may have been evicted. | +| `PENDING` | Work is queued. Previous output may be withheld because its sources changed or became inaccessible. | +| `READY` | A value is available. Check `stale` and coverage fields. | +| `EMPTY` | No sources match. There is no generated value. | +| `REFRESHING` | New work is running. A last good value can remain. | +| `FAILED` | Inspect `errorCode`. A last good value may remain, or `value` may be absent. | `stale` is independent of status. It compares the result with the current definition and source changes. Decide whether to use a last good stale value, wait, or fall back to direct recall. Do not turn an absent value into an empty summary. @@ -200,22 +200,22 @@ Result reads validate contributing source records. Deleted, changed, or newly in ## Filter and group sources -Use `filter` for owners, sessions, stable namespace IDs, topics, memory types, creation times, and typed attributes. `filterOp` defaults to `all`; `any` combines optional filters with OR. Exact partition scope and time-window restrictions apply separately, as do ownership checks in on-prem deployments. Legacy `namespace` labels are unsupported for Summary Views; use `namespaceRef`. +Use `filter` for owners, sessions, stable namespace IDs, topics, memory types, creation times, and typed attributes. `filter.op` defaults to `ALL`; `ANY` combines optional filters with OR. Exact partition scope and time-window restrictions apply separately, as do ownership checks in on-prem deployments. Legacy `namespace` labels are unsupported for Summary Views; use `namespaceId`. -`groupBy` accepts up to four distinct fields: `ownerId`, `sessionId`, `namespaceRef`, and `memoryType`. A result read or `target: partition` refresh must supply exactly those fields. Missing or extra scope fields are invalid. `groupBy: []` creates a singleton; omit all scope fields when reading it. +`groupBy` accepts up to four distinct fields: `ownerId`, `sessionId`, `namespaceId`, and `memoryType`. A result read or `target: PARTITION` refresh must supply exactly those fields. Missing or extra scope fields are invalid. `groupBy: []` creates a singleton; omit all scope fields when reading it. -For `groupBy: ["ownerId", "namespaceRef"]`, use this partition refresh body: +For `groupBy: ["ownerId", "namespaceId"]`, use this partition refresh body: ```json { - "target": "partition", - "scope": {"ownerId":"","namespaceRef":""} + "target": "PARTITION", + "scope": {"ownerId":"","namespaceId":""} } ``` -Send the same scope as query parameters on result reads. Here `namespaceRef` is an ID string, not the `{"namespaceId":"..."}` object used to place a memory. `target: full` reconciles current and previous partitions. +Send the same scope as query parameters on result reads. `target: FULL` reconciles current and previous partitions. -`evictionPolicy.maxPartitions` bounds grouped results within the deployment limit. Grouped views use the operator's partition limit when the policy is omitted; singleton views omit it. Matching source mutations make a scope recent; reads do not. Evicted scopes can return `cold`. `timeWindowSeconds` selects sources by creation time in a rolling window; it does not change source retention. +`evictionPolicy.maxPartitions` bounds grouped results within the deployment limit. Grouped views use the operator's partition limit when the policy is omitted; singleton views omit it. Matching source mutations make a scope recent; reads do not. Evicted scopes can return `COLD`. `timeWindowSeconds` selects sources by creation time in a rolling window; it does not change source retention. ## Choose structured output and continuous refresh @@ -223,23 +223,23 @@ For structured output, replace `output` with: ```json { - "format": "structured", + "format": "STRUCTURED", "instructions": "Summarize only preferences supported by the selected memories.", "schema": { "fields": [ - {"name":"cities","type":"list[str]","description":"Cities the user wants to visit"}, - {"name":"vegetarian","type":"bool","description":"Whether the user has stated a vegetarian diet"} + {"name":"cities","type":"STRING_LIST","description":"Cities the user wants to visit"}, + {"name":"vegetarian","type":"BOOLEAN","description":"Whether the user has stated a vegetarian diet"} ] } } ``` -The schema accepts 1–50 fields of type `str`, `int`, `float`, `bool`, `list[str]`, `list[float]`, or `object`. Generated fields are optional. Arbitrary JSON Schema, required-field declarations, and nested object schemas are unsupported. Text output must omit `schema`; structured output requires it. Invalid generated data is reported as `OUTPUT_VALIDATION_FAILED`. +The schema accepts 1–50 fields of type `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `STRING_LIST`, `FLOAT_LIST`, or `OBJECT`. Generated fields are optional. Arbitrary JSON Schema, required-field declarations, and nested object schemas are unsupported. Text output must omit `schema`; structured output requires it. Invalid generated data is reported as `OUTPUT_VALIDATION_FAILED`. For continuous refresh, use: ```json -{"mode":"continuous","debounceSeconds":5,"reconcileIntervalSeconds":60} +{"mode":"CONTINUOUS","debounceSeconds":5,"reconcileIntervalSeconds":60} ``` The reconcile interval is required and must fit deployment limits. Debounce coalesces mutations; reconciliation also handles changes such as a moving time window. Manual mode omits both interval fields. Both modes run asynchronously within queue, source, generation, and concurrency limits. @@ -257,7 +257,7 @@ Request `includeSourceMemoryIds=true` for the selected source IDs. These identif | Update a definition | `update_summary_view_async` | `updateSummaryView` | `PATCH /summary-views/{viewId}` | | Delete a definition | `delete_summary_view_async` | `deleteSummaryView` | `DELETE /summary-views/{viewId}` | -REST paths are relative to `/v1/stores/{storeId}`. Lists return `items` and optional `nextPageToken`; pass it as `pageToken` with the same query. Definition states (`active`, `disabled`, `deleting`) are separate from result status. +REST paths are relative to `/iris/data/v1/agent-memory/stores/{storeId}`. Lists return `items` and optional `nextCursor`; pass it as `cursor` with the same query. Definition states (`ACTIVE`, `DISABLED`, `DELETING`) are separate from result status. | Change | Effect | |:-------|:-------|