@ancplua/qyl-api-schema 11.6.0-rc.1 → 12.0.0

package/generated/json-schema/qyl-api-schema.json

@@ -479,50 +479,26 @@
       },
       "description": "A reference to an OpenTelemetry entity described by attributes on the containing Resource."
     },
-    "Common.Errors.ApiError": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/Common.Errors.NotFoundError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.ValidationError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.UnauthorizedError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.ForbiddenError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.ConflictError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.PreconditionFailedError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.PreconditionRequiredError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.RateLimitError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.InternalServerError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.BadGatewayError"
-        },
-        {
-          "$ref": "#/$defs/Common.Errors.ServiceUnavailableError"
-        }
-      ],
-      "description": "Standard error response types"
-    },
     "Common.Errors.BadGatewayError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/bad-gateway"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "bad_gateway"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -531,7 +507,7 @@
         },
         "dependency": {
           "type": "string",
-          "description": "Stable dependency category; never contains raw exception text"
+          "description": "Stable dependency category; never raw exception text."
         }
       },
       "unevaluatedProperties": {
@@ -542,14 +518,28 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Upstream dependency failed while fulfilling the request (502)"
+      "description": "An upstream dependency failed while the server handled the request (502)."
     },
     "Common.Errors.ConflictError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/conflict"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "conflict"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -558,7 +548,7 @@
         },
         "conflicting_resource": {
           "type": "string",
-          "description": "The conflicting resource ID"
+          "description": "The identifier of the conflicting resource."
         }
       },
       "unevaluatedProperties": {
@@ -569,14 +559,28 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Conflict - resource state conflict (409)"
+      "description": "The request conflicts with the current state of a resource (409)."
     },
     "Common.Errors.ForbiddenError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/forbidden"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "forbidden"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -585,7 +589,7 @@
         },
         "required_permission": {
           "type": "string",
-          "description": "Required permission that is missing"
+          "description": "The permission the credential lacks."
         }
       },
       "unevaluatedProperties": {
@@ -596,23 +600,33 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Forbidden - insufficient permissions (403)"
+      "description": "The credential is valid but not allowed to do this (403)."
     },
     "Common.Errors.InternalServerError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
-        "title": {
+        "type": {
           "type": "string",
           "enum": [
-            "Internal Server Error"
+            "https://qyl.at/problems/internal-error"
           ]
         },
-        "error_code": {
+        "code": {
+          "type": "string",
+          "enum": [
+            "internal_error"
+          ]
+        },
+        "title": {
           "type": "string",
-          "description": "Error code for support reference"
+          "enum": [
+            "Internal Server Error"
+          ]
         }
       },
       "unevaluatedProperties": {
@@ -623,14 +637,28 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Internal server error (500)"
+      "description": "The server failed while handling the request (500)."
     },
     "Common.Errors.NotFoundError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/not-found"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "not_found"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -639,11 +667,11 @@
         },
         "resource_type": {
           "type": "string",
-          "description": "The type of resource that was not found"
+          "description": "The kind of resource that was not found."
         },
         "resource_id": {
           "type": "string",
-          "description": "The identifier that was not found"
+          "description": "The identifier that was not found."
         }
       },
       "unevaluatedProperties": {
@@ -654,14 +682,28 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Resource not found (404)"
+      "description": "The addressed resource does not exist (404)."
     },
     "Common.Errors.PreconditionFailedError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/precondition-failed"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "precondition_failed"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -670,7 +712,7 @@
         },
         "current_etag": {
           "type": "string",
-          "description": "Entity tag of the current version, when the caller may read it"
+          "description": "Entity tag of the current version, when the caller may read it."
         }
       },
       "unevaluatedProperties": {
@@ -681,14 +723,28 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Precondition failed - the If-Match entity tag is no longer current (412)"
+      "description": "The If-Match entity tag is no longer current (412)."
     },
     "Common.Errors.PreconditionRequiredError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/precondition-required"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "precondition_required"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -700,7 +756,7 @@
           "enum": [
             "If-Match"
           ],
-          "description": "The header the request must carry"
+          "description": "The header the request must carry."
         }
       },
       "unevaluatedProperties": {
@@ -711,77 +767,98 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Precondition required - the request must send If-Match (428)"
+      "description": "The request must send If-Match (428)."
+    },
+    "Common.Errors.ProblemCode": {
+      "type": "string",
+      "enum": [
+        "validation_failed",
+        "unauthorized",
+        "forbidden",
+        "not_found",
+        "conflict",
+        "precondition_failed",
+        "precondition_required",
+        "internal_error",
+        "bad_gateway",
+        "service_unavailable"
+      ],
+      "description": "Stable machine-readable code of a problem type, the qyl `code` extension\nmember. `type` names the same problem type as a URI."
     },
     "Common.Errors.ProblemDetails": {
       "type": "object",
       "required": [
         "type",
         "title",
-        "status"
+        "status",
+        "code"
       ],
       "properties": {
         "type": {
-          "type": "string",
-          "format": "uri",
-          "description": "A URI reference identifying the problem type",
-          "default": "about:blank"
+          "$ref": "#/$defs/Common.Errors.ProblemType",
+          "description": "URI of the problem type."
         },
         "title": {
           "type": "string",
-          "description": "A short, human-readable summary of the problem type"
+          "description": "Short summary of the problem type; the same for every occurrence."
         },
         "status": {
           "type": "integer",
           "format": "int32",
-          "description": "The HTTP status code (informational only, actual code set by subtype)"
+          "description": "HTTP status code of this response, repeated for the reader of the body."
         },
         "detail": {
           "type": "string",
-          "description": "A human-readable explanation specific to this occurrence"
+          "description": "Explanation specific to this occurrence."
         },
         "instance": {
           "type": "string",
           "format": "uri",
-          "description": "A URI reference identifying the specific occurrence"
+          "description": "URI reference identifying this occurrence."
         },
-        "timestamp": {
-          "type": "string",
-          "format": "date-time",
-          "description": "Timestamp of the error"
+        "code": {
+          "$ref": "#/$defs/Common.Errors.ProblemCode",
+          "description": "Stable code of the problem type."
         }
       },
-      "description": "RFC 7807 Problem Details for HTTP APIs"
+      "description": "RFC 9457 problem details, served as application/problem+json: the standard members plus the qyl `code` extension."
+    },
+    "Common.Errors.ProblemType": {
+      "type": "string",
+      "enum": [
+        "https://qyl.at/problems/validation-failed",
+        "https://qyl.at/problems/unauthorized",
+        "https://qyl.at/problems/forbidden",
+        "https://qyl.at/problems/not-found",
+        "https://qyl.at/problems/conflict",
+        "https://qyl.at/problems/precondition-failed",
+        "https://qyl.at/problems/precondition-required",
+        "https://qyl.at/problems/internal-error",
+        "https://qyl.at/problems/bad-gateway",
+        "https://qyl.at/problems/service-unavailable"
+      ],
+      "description": "Problem type URI, the RFC 9457 `type` member: one per problem a qyl server\nreports. `code` names the same problem type."
     },
-    "Common.Errors.RateLimitError": {
+    "Common.Errors.ServiceUnavailableError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
-        "title": {
+        "type": {
           "type": "string",
           "enum": [
-            "Too Many Requests"
+            "https://qyl.at/problems/service-unavailable"
           ]
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "allOf": [
-        {
-          "$ref": "#/$defs/Common.Errors.ProblemDetails"
-        }
-      ],
-      "description": "Rate limited - too many requests (429)"
-    },
-    "Common.Errors.ServiceUnavailableError": {
-      "type": "object",
-      "required": [
-        "title"
-      ],
-      "properties": {
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "service_unavailable"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -795,7 +872,7 @@
             "overloaded",
             "dependency_failure"
           ],
-          "description": "Reason for unavailability"
+          "description": "Why the server is unavailable."
         }
       },
       "unevaluatedProperties": {
@@ -806,14 +883,28 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Service unavailable (503)"
+      "description": "The server cannot take the request at present (503)."
     },
     "Common.Errors.UnauthorizedError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/unauthorized"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "unauthorized"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -829,15 +920,29 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Unauthorized - authentication required (401)"
+      "description": "The request carries no valid credential (401)."
     },
     "Common.Errors.ValidationError": {
       "type": "object",
       "required": [
+        "type",
+        "code",
         "title",
         "errors"
       ],
       "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "https://qyl.at/problems/validation-failed"
+          ]
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "validation_failed"
+          ]
+        },
         "title": {
           "type": "string",
           "enum": [
@@ -849,7 +954,7 @@
           "items": {
             "$ref": "#/$defs/Common.Errors.ValidationErrorDetail"
           },
-          "description": "List of validation errors"
+          "description": "Each rule the request broke."
         }
       },
       "unevaluatedProperties": {
@@ -860,7 +965,7 @@
           "$ref": "#/$defs/Common.Errors.ProblemDetails"
         }
       ],
-      "description": "Bad request - validation failed (400)"
+      "description": "The request failed validation (400)."
     },
     "Common.Errors.ValidationErrorDetail": {
       "type": "object",
@@ -872,25 +977,25 @@
       "properties": {
         "field": {
           "type": "string",
-          "description": "The field/property that failed validation"
+          "description": "The field or parameter that failed validation."
         },
         "message": {
           "type": "string",
-          "description": "The error message"
+          "description": "What is wrong with it."
         },
         "code": {
           "type": "string",
-          "description": "The validation rule that failed"
+          "description": "The validation rule that failed."
         },
         "rejected_value": {
           "type": "string",
-          "description": "The rejected value (if safe to include)"
+          "description": "The rejected value, when it is safe to repeat."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Individual validation error detail"
+      "description": "One rule a request broke."
     },
     "Common.HttpMethod": {
       "type": "string",
@@ -970,158 +1075,12 @@
         "00:1A:2B:3C:4D:5E"
       ]
     },
-    "Common.Pagination.AggregationParams": {
-      "type": "object",
-      "properties": {
-        "bucket": {
-          "$ref": "#/$defs/Common.Pagination.TimeBucket",
-          "description": "Time bucket size",
-          "default": "auto"
-        },
-        "group_by": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Group by these dimensions"
-        },
-        "filter": {
-          "type": "string",
-          "description": "Filter expression"
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "description": "Aggregation query parameters"
-    },
-    "Common.Pagination.CursorPaginationParams": {
-      "type": "object",
-      "properties": {
-        "cursor": {
-          "type": "string",
-          "description": "Opaque cursor for fetching the next page"
-        },
-        "limit": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "maximum": 1000,
-          "description": "Maximum number of items to return (1-1000)",
-          "default": 100
-        },
-        "order": {
-          "$ref": "#/$defs/Common.Pagination.SortOrder",
-          "description": "Sort direction",
-          "default": "desc"
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "description": "Cursor-based pagination parameters"
-    },
-    "Common.Pagination.OffsetPaginationParams": {
-      "type": "object",
-      "properties": {
-        "page": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "description": "Page number (1-indexed)",
-          "default": 1
-        },
-        "page_size": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "maximum": 1000,
-          "description": "Items per page (1-1000)",
-          "default": 100
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "description": "Offset-based pagination parameters"
-    },
-    "Common.Pagination.SortOrder": {
-      "type": "string",
-      "enum": [
-        "asc",
-        "desc"
-      ],
-      "description": "Sort order"
-    },
-    "Common.Pagination.StreamParams": {
-      "type": "object",
-      "properties": {
-        "since": {
-          "type": "string",
-          "format": "date-time",
-          "description": "Include historical data from this timestamp"
-        },
-        "trace_id": {
-          "$ref": "#/$defs/Common.TraceId",
-          "description": "Filter by trace ID"
-        },
-        "service_name": {
-          "type": "string",
-          "description": "Filter by service name"
-        },
-        "max_events_per_second": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "maximum": 1000,
-          "description": "Maximum events per second (rate limiting)",
-          "default": 100
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "description": "Streaming parameters for SSE endpoints"
-    },
-    "Common.Pagination.TimeBucket": {
-      "type": "string",
-      "enum": [
-        "1m",
-        "5m",
-        "15m",
-        "1h",
-        "1d",
-        "1w",
-        "auto"
-      ],
-      "description": "Time bucket size for aggregations"
-    },
-    "Common.Pagination.TimeRangeParams": {
-      "type": "object",
-      "properties": {
-        "start_time": {
-          "type": "string",
-          "format": "date-time",
-          "description": "Start of time range (inclusive)"
-        },
-        "end_time": {
-          "type": "string",
-          "format": "date-time",
-          "description": "End of time range (exclusive)"
-        },
-        "limit": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "maximum": 10000,
-          "description": "Maximum number of items to return",
-          "default": 1000
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "description": "Time-range based query parameters"
+    "Common.Pagination.PageLimit": {
+      "type": "integer",
+      "format": "int32",
+      "minimum": 1,
+      "maximum": 1000,
+      "description": "Page size of a list operation: at least 1 and at most 1000 items."
     },
     "Common.Percentage": {
       "type": "number",
@@ -2274,11 +2233,11 @@
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         },
         "error": {
           "$ref": "#/$defs/Mcp.Tools.ToolError",
@@ -2391,11 +2350,11 @@
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         },
         "error": {
           "$ref": "#/$defs/Mcp.Tools.ToolError",
@@ -2444,11 +2403,11 @@
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         },
         "error": {
           "$ref": "#/$defs/Mcp.Tools.ToolError",
@@ -2514,11 +2473,11 @@
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         },
         "annotations": {
           "type": "array",
@@ -2595,11 +2554,11 @@
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         },
         "error": {
           "$ref": "#/$defs/Mcp.Tools.ToolError",
@@ -2983,11 +2942,8 @@
           "format": "date-time"
         },
         "limit": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "maximum": 1000,
-          "description": "Page size for trace and log runs.",
+          "$ref": "#/$defs/Common.Pagination.PageLimit",
+          "description": "Page size for trace and log runs; 100 when omitted.",
           "default": 100
         },
         "cursor": {
@@ -3108,11 +3064,11 @@
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         },
         "error": {
           "$ref": "#/$defs/Mcp.Tools.ToolError",
@@ -3179,11 +3135,11 @@
       "properties": {
         "has_more": {
           "type": "boolean",
-          "description": "Whether more items exist beyond this page. False only when the result is complete."
+          "description": "Whether more items exist beyond this page. False only when the result is complete; `next_cursor` is present exactly when this is true."
         },
         "next_cursor": {
           "$ref": "#/$defs/Common.Cursor",
-          "description": "Pass as `cursor` to the same tool with the same filters for the next page."
+          "description": "Pass as `cursor` to the same tool with the same filters for the next page. Absent on the last page."
         }
       },
       "unevaluatedProperties": {
@@ -4170,51 +4126,6 @@
       },
       "description": "Link to another span (e.g., batch processing)"
     },
-    "OTel.Traces.SpanQueryFilters": {
-      "type": "object",
-      "properties": {
-        "trace_id": {
-          "$ref": "#/$defs/Common.TraceId",
-          "description": "Filter by trace ID"
-        },
-        "parent_span_id": {
-          "$ref": "#/$defs/Common.SpanId",
-          "description": "Filter by parent span ID"
-        },
-        "name": {
-          "type": "string",
-          "description": "Filter by span name (supports wildcards)"
-        },
-        "kind": {
-          "$ref": "#/$defs/OTel.Enums.SpanKind",
-          "description": "Filter by span kind"
-        },
-        "service_name": {
-          "type": "string",
-          "description": "Filter by service name"
-        },
-        "status_code": {
-          "$ref": "#/$defs/OTel.Enums.SpanStatusCode",
-          "description": "Filter by status code"
-        },
-        "min_duration_ns": {
-          "$ref": "#/$defs/Common.DurationNs",
-          "description": "Minimum duration in nanoseconds"
-        },
-        "max_duration_ns": {
-          "$ref": "#/$defs/Common.DurationNs",
-          "description": "Maximum duration in nanoseconds"
-        },
-        "attribute": {
-          "type": "string",
-          "description": "Filter by attribute key-value pair"
-        }
-      },
-      "unevaluatedProperties": {
-        "not": {}
-      },
-      "description": "Filter parameters for querying spans"
-    },
     "OTel.Traces.SpanStats": {
       "type": "object",
       "required": [
@@ -4601,10 +4512,12 @@
           }
         },
         "next_cursor": {
-          "$ref": "#/$defs/Common.Cursor"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Pass back as `cursor` for the next page of the same run. Absent on the last page."
         },
         "has_more": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
@@ -4777,11 +4690,8 @@
           "format": "date-time"
         },
         "limit": {
-          "type": "integer",
-          "format": "int32",
-          "minimum": 1,
-          "maximum": 1000,
-          "description": "Page size for trace and log runs.",
+          "$ref": "#/$defs/Common.Pagination.PageLimit",
+          "description": "Page size for trace and log runs; 100 when omitted.",
           "default": 100
         },
         "cursor": {
@@ -4910,10 +4820,12 @@
           }
         },
         "next_cursor": {
-          "$ref": "#/$defs/Common.Cursor"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Pass back as `cursor` for the next page of the same run. Absent on the last page."
         },
         "has_more": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
@@ -5640,7 +5552,8 @@
           }
         },
         "next_cursor": {
-          "type": "string"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         }
       },
       "unevaluatedProperties": {
@@ -6074,7 +5987,8 @@
           }
         },
         "next_cursor": {
-          "type": "string"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         }
       },
       "unevaluatedProperties": {
@@ -6566,7 +6480,8 @@
           }
         },
         "next_cursor": {
-          "type": "string"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         }
       },
       "unevaluatedProperties": {
@@ -7217,7 +7132,8 @@
           }
         },
         "next_cursor": {
-          "type": "string"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         }
       },
       "unevaluatedProperties": {
@@ -7381,7 +7297,8 @@
           }
         },
         "next_cursor": {
-          "type": "string"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         }
       },
       "unevaluatedProperties": {
@@ -7667,25 +7584,21 @@
           "items": {
             "$ref": "#/$defs/Annotations.Annotation"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.AnnotationsApi_list.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -7735,25 +7648,21 @@
           "items": {
             "$ref": "#/$defs/OTel.Logs.LogRecord"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.LogsApi_list.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -7776,25 +7685,21 @@
           "items": {
             "$ref": "#/$defs/OTel.Metrics.MetricDescriptor"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.MetricsApi_list.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -7817,25 +7722,21 @@
           "items": {
             "$ref": "#/$defs/OTel.Metrics.MetricSeries"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.MetricsApi_listSeries.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -8011,25 +7912,21 @@
           "items": {
             "$ref": "#/$defs/SavedQueries.SavedQuery"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.SavedQueriesApi_list.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -8124,25 +8021,21 @@
           "items": {
             "$ref": "#/$defs/OTel.Traces.Trace"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.SessionsApi_getTraces.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -8168,25 +8061,21 @@
           "items": {
             "$ref": "#/$defs/Domains.Observe.Session.SessionEntity"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.SessionsApi_list.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -8233,25 +8122,21 @@
           "items": {
             "$ref": "#/$defs/OTel.Traces.Span"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.TracesApi_getSpans.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"
@@ -8277,25 +8162,21 @@
           "items": {
             "$ref": "#/$defs/OTel.Traces.Trace"
           },
-          "description": "List of items in this page"
+          "description": "The items of this page."
         },
         "next_cursor": {
-          "type": "string",
-          "description": "Cursor for the next page (null if no more pages)"
-        },
-        "prev_cursor": {
-          "type": "string",
-          "description": "Cursor for the previous page (null if first page)"
+          "$ref": "#/$defs/Common.Cursor",
+          "description": "Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page."
         },
         "has_more": {
           "type": "boolean",
-          "description": "Whether there are more items available"
+          "description": "Whether more items follow this page. `next_cursor` is present exactly when this is true."
         }
       },
       "unevaluatedProperties": {
         "not": {}
       },
-      "description": "Cursor-based paginated response wrapper"
+      "description": "One page of a list operation."
     },
     "Operations.TracesApi_list.Response.400": {
       "$ref": "#/$defs/Common.Errors.ValidationError"