From fd32b980b4110973f3f5a27edf8fdd7f485c8dd8 Mon Sep 17 00:00:00 2001 From: Kartik Date: Mon, 3 Aug 2026 23:41:24 +0530 Subject: [PATCH] docs(openapi): complete parameter and description coverage for current v1 memory routes (#6775) --- docs/openapi.json | 258 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 229 insertions(+), 29 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 468ed2993..0bc42eb72 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1878,6 +1878,24 @@ ], "description": "Despite the endpoint name, this returns memory history entries (the same shape as `GET /v1/memories/{memory_id}/history/`), not event/ingestion-job records. For event/ingestion-job status, use `GET /v1/event/{event_id}/`.", "operationId": "memories_events_list", + "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Page number for pagination. Default: 1. Default page size is 100." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Number of items per page. Default: 100." + } + ], "responses": { "200": { "description": "Successfully retrieved memory history entries.", @@ -1940,6 +1958,21 @@ "type": "string", "description": "The identifier of the user associated with this memory" }, + "agent_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the agent associated with this memory, if any." + }, + "app_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the app associated with this memory, if any." + }, + "session_id": { + "type": "string", + "nullable": true, + "description": "The run identifier associated with this memory, returned as `session_id`." + }, "categories": { "type": "array", "nullable": true, @@ -2004,6 +2037,22 @@ } } } + }, + "404": { + "description": "Invalid page.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "detail": { + "type": "string", + "example": "Invalid page." + } + } + } + } + } } } } @@ -3114,7 +3163,42 @@ "tags": [ "memories" ], + "description": "Returns a paginated list of memories belonging to the given entity.", "operationId": "memories_entity_read", + "parameters": [ + { + "name": "entity_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "user", + "agent", + "run", + "app" + ] + }, + "description": "The type of entity to retrieve memories for. Any other value returns `400 {\"error\": \"Invalid entity type\"}`." + }, + { + "name": "entity_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The identifier of the entity whose memories to retrieve." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Page number for pagination. Default: 1. Page size is fixed at 100 and is not client-configurable." + } + ], "responses": { "200": { "description": "Successfully retrieved memories.", @@ -3218,34 +3302,25 @@ } } } - } - } - }, - "parameters": [ - { - "name": "entity_type", - "in": "path", - "required": true, - "schema": { - "type": "string", - "enum": [ - "user", - "agent", - "run", - "app" - ] }, - "description": "The type of entity to retrieve memories for." - }, - { - "name": "entity_id", - "in": "path", - "required": true, - "schema": { - "type": "string" + "404": { + "description": "Invalid page.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "detail": { + "type": "string", + "example": "Invalid page." + } + } + } + } + } } } - ] + } }, "/v1/memories/{memory_id}/": { "get": { @@ -3288,6 +3363,21 @@ "nullable": true, "description": "Identifier of the user associated with this memory" }, + "agent_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the agent associated with this memory, if any." + }, + "app_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the app associated with this memory, if any." + }, + "session_id": { + "type": "string", + "nullable": true, + "description": "The run identifier associated with this memory, returned as `session_id`." + }, "metadata": { "type": "object", "additionalProperties": true, @@ -3339,6 +3429,22 @@ } } }, + "400": { + "description": "Invalid memory ID.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "memory_id should be a valid UUID" + } + } + } + } + } + }, "404": { "description": "Memory not found.", "content": { @@ -3387,7 +3493,7 @@ "tags": [ "memories" ], - "description": "Get or Update or delete a memory.", + "description": "Update a memory's text, metadata, or expiration date.", "operationId": "memories_update", "parameters": [ { @@ -3398,7 +3504,7 @@ "type": "string", "format": "uuid" }, - "description": "The unique identifier of the memory to retrieve." + "description": "The unique identifier of the memory to update." } ], "requestBody": { @@ -3448,6 +3554,21 @@ "nullable": true, "description": "Identifier of the user associated with this memory" }, + "agent_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the agent associated with this memory, if any." + }, + "app_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the app associated with this memory, if any." + }, + "session_id": { + "type": "string", + "nullable": true, + "description": "The run identifier associated with this memory, returned as `session_id`." + }, "metadata": { "type": "object", "additionalProperties": true, @@ -3498,6 +3619,38 @@ } } } + }, + "400": { + "description": "Invalid memory ID.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "memory_id should be a valid UUID" + } + } + } + } + } + }, + "404": { + "description": "Memory not found.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "Memory not found!" + } + } + } + } + } } }, "x-code-samples": [ @@ -3532,7 +3685,7 @@ "tags": [ "memories" ], - "description": "Get or Update or delete a memory.", + "description": "Delete a memory.", "operationId": "memories_delete", "parameters": [ { @@ -3543,7 +3696,7 @@ "type": "string", "format": "uuid" }, - "description": "The unique identifier of the memory to retrieve." + "description": "The unique identifier of the memory to delete." }, { "name": "delete_linked", @@ -3575,6 +3728,38 @@ } } } + }, + "400": { + "description": "Invalid memory ID.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "memory_id should be a valid UUID" + } + } + } + } + } + }, + "404": { + "description": "Memory not found.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "Memory not found!" + } + } + } + } + } } }, "x-code-samples": [ @@ -3682,6 +3867,21 @@ "type": "string", "description": "The identifier of the user associated with this memory" }, + "agent_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the agent associated with this memory, if any." + }, + "app_id": { + "type": "string", + "nullable": true, + "description": "The identifier of the app associated with this memory, if any." + }, + "session_id": { + "type": "string", + "nullable": true, + "description": "The run identifier associated with this memory, returned as `session_id`." + }, "categories": { "type": "array", "nullable": true,