From dd54e387de195bffe61deb85c4251af2ec0ad116 Mon Sep 17 00:00:00 2001
From: Kartik <kartik.labhshetwar@mem0.ai>
Date: Mon, 3 Aug 2026 23:56:12 +0530
Subject: [PATCH] docs(openapi): document limit param and error responses on
 GET /v1/memories/ (#6779)

---
 docs/openapi.json | 59 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 2 deletions(-)

diff --git a/docs/openapi.json b/docs/openapi.json
index 0bc42eb72..9770b590a 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -1218,6 +1218,15 @@
 						},
 						"description": "Number of items per page. Default: 100."
 					},
+					{
+						"name": "limit",
+						"in": "query",
+						"schema": {
+							"type": "integer",
+							"maximum": 200
+						},
+						"description": "Maximum number of memories to return. Maximum accepted value: 200. Ignored when both `page` and `page_size` are supplied."
+					},
 					{
 						"name": "start_date",
 						"in": "query",
@@ -1261,6 +1270,7 @@
 													},
 													"metadata": {
 														"type": "object",
+														"nullable": true,
 														"additionalProperties": true,
 														"description": "User-supplied metadata attached to the memory."
 													},
@@ -1288,6 +1298,7 @@
 													},
 													"structured_attributes": {
 														"type": "object",
+														"nullable": true,
 														"additionalProperties": true,
 														"description": "System-derived temporal breakdown of the memory's creation time (e.g. year, month, day_of_week)."
 													},
@@ -1346,6 +1357,7 @@
 															},
 															"metadata": {
 																"type": "object",
+																"nullable": true,
 																"additionalProperties": true,
 																"description": "User-supplied metadata attached to the memory."
 															},
@@ -1373,6 +1385,7 @@
 															},
 															"structured_attributes": {
 																"type": "object",
+																"nullable": true,
 																"additionalProperties": true,
 																"description": "System-derived temporal breakdown of the memory's creation time (e.g. year, month, day_of_week)."
 															},
@@ -1413,14 +1426,47 @@
 					},
 					"400": {
 						"description": "Bad Request.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"oneOf": [
+										{
+											"type": "array",
+											"description": "Returned when none of the required filters (app_id, user_id, agent_id, run_id) is supplied.",
+											"items": {
+												"type": "string"
+											},
+											"example": [
+												"One of the filters: app_id, user_id, agent_id, run_id is required!"
+											]
+										},
+										{
+											"type": "object",
+											"description": "Returned when the `limit` query parameter is invalid.",
+											"properties": {
+												"error": {
+													"type": "string"
+												}
+											},
+											"example": {
+												"error": "limit must be <= 200"
+											}
+										}
+									]
+								}
+							}
+						}
+					},
+					"404": {
+						"description": "Not Found.",
 						"content": {
 							"application/json": {
 								"schema": {
 									"type": "object",
 									"properties": {
-										"message": {
+										"detail": {
 											"type": "string",
-											"example": "One of the filters: app_id, user_id, agent_id, run_id is required!"
+											"example": "Invalid page."
 										}
 									}
 								}
@@ -1774,6 +1820,7 @@
 											},
 											"metadata": {
 												"type": "object",
+												"nullable": true,
 												"additionalProperties": true,
 												"description": "Additional metadata associated with the memory"
 											},
@@ -1802,6 +1849,7 @@
 											},
 											"structured_attributes": {
 												"type": "object",
+												"nullable": true,
 												"additionalProperties": true,
 												"description": "System-derived temporal breakdown of the memory's creation time (e.g. year, month, day_of_week)."
 											},
@@ -2563,6 +2611,7 @@
 													},
 													"metadata": {
 														"type": "object",
+														"nullable": true,
 														"additionalProperties": true,
 														"description": "User-supplied metadata attached to the memory."
 													},
@@ -2575,6 +2624,7 @@
 													},
 													"structured_attributes": {
 														"type": "object",
+														"nullable": true,
 														"additionalProperties": true,
 														"description": "System-derived temporal breakdown of the memory's creation time (e.g. year, month, day_of_week)."
 													},
@@ -3082,6 +3132,7 @@
 													},
 													"metadata": {
 														"type": "object",
+														"nullable": true,
 														"additionalProperties": true,
 														"description": "User-supplied metadata attached to the memory."
 													},
@@ -3380,6 +3431,7 @@
 										},
 										"metadata": {
 											"type": "object",
+											"nullable": true,
 											"additionalProperties": true,
 											"description": "Additional metadata associated with the memory"
 										},
@@ -3408,6 +3460,7 @@
 										},
 										"structured_attributes": {
 											"type": "object",
+											"nullable": true,
 											"additionalProperties": true,
 											"description": "System-derived temporal breakdown of the memory's creation time (e.g. year, month, day_of_week)."
 										},
@@ -3571,6 +3624,7 @@
 										},
 										"metadata": {
 											"type": "object",
+											"nullable": true,
 											"additionalProperties": true,
 											"description": "Additional metadata associated with the memory"
 										},
@@ -3599,6 +3653,7 @@
 										},
 										"structured_attributes": {
 											"type": "object",
+											"nullable": true,
 											"additionalProperties": true,
 											"description": "System-derived temporal breakdown of the memory's creation time (e.g. year, month, day_of_week)."
 										},